diff --git a/docs/core/diagnostics/dotnet-dump.md b/docs/core/diagnostics/dotnet-dump.md index 84570b91e4fd3..eed83a6307086 100644 --- a/docs/core/diagnostics/dotnet-dump.md +++ b/docs/core/diagnostics/dotnet-dump.md @@ -169,7 +169,7 @@ dotnet-dump analyze [-h|--help] [-c|--command] | `dumpgcdata` | Displays information about the GC data. | | `dumpgen` | Displays heap content for the specified generation. | | `dumpheap` | Displays info about the garbage-collected heap and collection statistics about objects. | -| `dumpil` | Displays the Microsoft intermediate language (MSIL) that's associated with a managed method. | +| `dumpil` | Displays the common intermediate language (CIL) that's associated with a managed method. | | `dumplog` | Writes the contents of an in-memory stress log to the specified file. | | `dumpmd` | Displays information about the `MethodDesc` structure at the specified address. | | `dumpmodule` | Displays information about the module at the specified address. | diff --git a/docs/core/diagnostics/sos-debugging-extension.md b/docs/core/diagnostics/sos-debugging-extension.md index 7c1cc184b1840..3f85bdcca865f 100644 --- a/docs/core/diagnostics/sos-debugging-extension.md +++ b/docs/core/diagnostics/sos-debugging-extension.md @@ -41,7 +41,7 @@ The following table of commands is also available under **Help** or **soshelp**. | **DumpClass** \<*EEClass address*> | Displays information about the `EEClass` structure associated with a type.

The **DumpClass** command displays static field values but does not display nonstatic field values.

Use the **DumpMT**, **DumpObj**, **Name2EE**, or **Token2EE** command to get an `EEClass` structure address. | | **DumpDomain** [\<*domain address*>] | Enumerates each object that's loaded within the specified object address. When called with no parameters, the **DumpDomain** command lists all objects in a process. Since .NET (Core) only has one , **DumpDomain** only returns one object. | | **DumpHeap** [**-stat**] [**-strings**] [**-short**] [**-min** \<*size*>] [**-max** \<*size*>] [**-thinlock**] [**-startAtLowerBound**] [**-mt** \<*MethodTable address*>] [**-type** \<*partial type name*>] [*start* [*end*]] | Displays information about the garbage-collected heap and collection statistics about objects.

The **DumpHeap** command displays a warning if it detects excessive fragmentation in the garbage collector heap.

The **-stat** option restricts the output to the statistical type summary.

The **-strings** option restricts the output to a statistical string value summary.

The **-short** option limits output to just the address of each object. This lets you easily pipe output from the command to another debugger command for automation.

The **-min** option ignores objects that are less than the `size` parameter, specified in bytes.

The **-max** option ignores objects that are larger than the `size` parameter, specified in bytes.

The **-thinlock** option reports ThinLocks. For more information, see the **SyncBlk** command.

The `-startAtLowerBound` option forces the heap walk to begin at the lower bound of a supplied address range. During the planning phase, the heap is often not walkable because objects are being moved. This option forces **DumpHeap** to begin its walk at the specified lower bound. You must supply the address of a valid object as the lower bound for this option to work. You can display memory at the address of a bad object to manually find the next method table. If the garbage collection is currently in a call to `memcopy`, you may also be able to find the address of the next object by adding the size to the start address, which is supplied as a parameter.

The **-mt** option lists only those objects that correspond to the specified `MethodTable` structure.

The **-type** option lists only those objects whose type name is a substring match of the specified string.

The `start` parameter begins listing from the specified address.

The `end` parameter stops listing at the specified address. | -| **DumpIL** \<*Managed DynamicMethod object*> | \<*DynamicMethodDesc pointer*> | \<*MethodDesc pointer*> | Displays the Microsoft intermediate language (MSIL) that is associated with a managed method.

Dynamic MSIL is emitted differently than MSIL that's loaded from an assembly. Dynamic MSIL refers to objects in a managed object array rather than to metadata tokens. | +| **DumpIL** \<*Managed DynamicMethod object*> | \<*DynamicMethodDesc pointer*> | \<*MethodDesc pointer*> | Displays the common intermediate language (CIL) that's associated with a managed method.

Dynamic CIL is emitted differently than CIL that's loaded from an assembly. Dynamic CIL refers to objects in a managed object array rather than to metadata tokens. | | **DumpLog** [**-addr** \<*addressOfStressLog*>] [<*Filename*>] | Writes the contents of an in-memory stress log to the specified file. If you do not specify a name, this command creates a file called StressLog.txt in the current directory.

The in-memory stress log helps you diagnose stress failures without using locks or I/O. To enable the stress log, set the following registry keys under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\\.NETFramework:

(DWORD) StressLog = 1

(DWORD) LogFacility = 0xffffffff

(DWORD) StressLogSize = 65536

The optional `-addr` option lets you specify a stress log other than the default log. | | **DumpMD** \<*MethodDesc address*> | Displays information about a `MethodDesc` structure at the specified address.

You can use the **IP2MD** command to get the `MethodDesc` structure address from a managed function. | | **DumpMT** [**-MD**] \<*MethodTable address*> | Displays information about a method table at the specified address. Specifying the **-MD** option displays a list of all methods defined with the object.

Each managed object contains a method table pointer. | @@ -135,7 +135,7 @@ By default you can reach all the SOS commands by entering: `sos [command_name]`. | `dumpgcdata` | Displays information about the GC data. | | `dumpgen` | Displays heap content for the specified generation. | | `dumpheap` | Displays info about the garbage-collected heap and collection statistics about objects. | -| `dumpil` | Displays the Microsoft intermediate language (MSIL) that's associated with a managed method. | +| `dumpil` | Displays the common intermediate language (CIL) that's associated with a managed method. | | `dumplog` | Writes the contents of an in-memory stress log to the specified file. | | `dumpmd` | Displays information about the `MethodDesc` structure at the specified address. | | `dumpmodule` | Displays information about the module at the specified address. | diff --git a/docs/core/whats-new/dotnet-8/containers.md b/docs/core/whats-new/dotnet-8/containers.md index 435f2ab7c206c..a7066d41bb2af 100644 --- a/docs/core/whats-new/dotnet-8/containers.md +++ b/docs/core/whats-new/dotnet-8/containers.md @@ -68,7 +68,7 @@ For more information, see the [Improving multi-platform container support](https ### ASP.NET composite images -As part of an effort to improve containerization performance, new ASP.NET Docker images are available that have a composite version of the runtime. This composite is built by compiling multiple MSIL assemblies into a single ready-to-run (R2R) output binary. Because these assemblies are embedded into a single image, jitting takes less time, and the startup performance of apps improves. The other big advantage of the composite over the regular ASP.NET image is that the composite images have a smaller size on disk. +As part of an effort to improve containerization performance, new ASP.NET Docker images are available that have a composite version of the runtime. This composite is built by compiling multiple CIL assemblies into a single ready-to-run (R2R) output binary. Because these assemblies are embedded into a single image, jitting takes less time, and the startup performance of apps improves. The other big advantage of the composite over the regular ASP.NET image is that the composite images have a smaller size on disk. There is a caveat to be aware of. Since composites have multiple assemblies embedded into one, they have tighter version coupling. Apps can't use custom versions of framework or ASP.NET binaries. diff --git a/docs/csharp/advanced-topics/expression-trees/index.md b/docs/csharp/advanced-topics/expression-trees/index.md index 798076ca42faf..b30434ba250c7 100644 --- a/docs/csharp/advanced-topics/expression-trees/index.md +++ b/docs/csharp/advanced-topics/expression-trees/index.md @@ -17,8 +17,8 @@ You've likely already written code that uses Expression trees. Entity Framework' When you want to have a richer interaction, you need to use *Expression Trees*. Expression Trees represent code as a structure that you examine, modify, or execute. These tools give you the power to manipulate code during run time. You write code that examines running algorithms, or injects new capabilities. In more advanced scenarios, you modify running algorithms and even translate C# expressions into another form for execution in another environment. You compile and run code represented by expression trees. Building and running expression trees enables dynamic modification of executable code, the execution of LINQ queries in various databases, and the creation of dynamic queries. For more information about expression trees in LINQ, see [How to use expression trees to build dynamic queries](../../programming-guide/concepts/linq/how-to-use-expression-trees-to-build-dynamic-queries.md). - -Expression trees are also used in the dynamic language runtime (DLR) to provide interoperability between dynamic languages and .NET and to enable compiler writers to emit expression trees instead of Microsoft intermediate language (MSIL). For more information about the DLR, see [Dynamic Language Runtime Overview](../../../framework/reflection-and-codedom/dynamic-language-runtime-overview.md). + +Expression trees are also used in the dynamic language runtime (DLR) to provide interoperability between dynamic languages and .NET and to enable compiler writers to emit expression trees instead of common intermediate language (CIL). For more information about the DLR, see [Dynamic Language Runtime Overview](../../../framework/reflection-and-codedom/dynamic-language-runtime-overview.md). You can have the C# or Visual Basic compiler create an expression tree for you based on an anonymous lambda expression, or you can create expression trees manually by using the namespace. diff --git a/docs/csharp/language-reference/compiler-options/security.md b/docs/csharp/language-reference/compiler-options/security.md index 4ba3fa72b183b..cec2cd22d057d 100644 --- a/docs/csharp/language-reference/compiler-options/security.md +++ b/docs/csharp/language-reference/compiler-options/security.md @@ -2,9 +2,9 @@ description: "C# Compiler Options for security. These options control signing assemblies or address space layout." title: "C# Compiler Options - security options" ms.date: 03/12/2021 -f1_keywords: +f1_keywords: - "cs.build.options" -helpviewer_keywords: +helpviewer_keywords: - "PublicSign compiler option [C#]" - "DelaySign compiler option [C#]" - "KeyFile compiler option [C#]" @@ -61,7 +61,7 @@ Specifies the name of the cryptographic key container. container ``` -`container` is the name of the strong name key container. When the **KeyContainer** option is used, the compiler creates a sharable component. The compiler inserts a public key from the specified container into the assembly manifest and signs the final assembly with the private key. To generate a key file, type `sn -k file` at the command line. `sn -i` installs the key pair into a container. This option isn't supported when the compiler runs on CoreCLR. To sign an assembly when building on CoreCLR, use the [**KeyFile**](#keyfile) option. If you compile with [**TargetType**](output.md#targettype), the name of the key file is held in the module and incorporated into the assembly when you compile this module into an assembly with [**AddModules**](inputs.md#addmodules). You can also specify this option as a custom attribute () in the source code for any Microsoft intermediate language (MSIL) module. You can also pass your encryption information to the compiler with [**KeyFile**](#keyfile). Use [**DelaySign**](#delaysign) to add the public key to the assembly manifest but signing the assembly until it has been tested. For more information, see [Creating and Using Strong-Named Assemblies](../../../standard/assembly/create-use-strong-named.md) and [Delay Signing an Assembly](../../../standard/assembly/delay-sign.md). +`container` is the name of the strong name key container. When the **KeyContainer** option is used, the compiler creates a sharable component. The compiler inserts a public key from the specified container into the assembly manifest and signs the final assembly with the private key. To generate a key file, type `sn -k file` at the command line. `sn -i` installs the key pair into a container. This option isn't supported when the compiler runs on CoreCLR. To sign an assembly when building on CoreCLR, use the [**KeyFile**](#keyfile) option. If you compile with [**TargetType**](output.md#targettype), the name of the key file is held in the module and incorporated into the assembly when you compile this module into an assembly with [**AddModules**](inputs.md#addmodules). You can also specify this option as a custom attribute () in the source code for any common intermediate language (CIL) module. You can also pass your encryption information to the compiler with [**KeyFile**](#keyfile). Use [**DelaySign**](#delaysign) to add the public key to the assembly manifest but signing the assembly until it has been tested. For more information, see [Creating and Using Strong-Named Assemblies](../../../standard/assembly/create-use-strong-named.md) and [Delay Signing an Assembly](../../../standard/assembly/delay-sign.md). ## HighEntropyVA diff --git a/docs/csharp/programming-guide/classes-and-structs/static-classes-and-static-class-members.md b/docs/csharp/programming-guide/classes-and-structs/static-classes-and-static-class-members.md index c835a6f63e6bc..d650dffa2bd94 100644 --- a/docs/csharp/programming-guide/classes-and-structs/static-classes-and-static-class-members.md +++ b/docs/csharp/programming-guide/classes-and-structs/static-classes-and-static-class-members.md @@ -2,7 +2,7 @@ title: "Static Classes and Static Class Members - C# Programming Guide" description: Static classes can't be instantiated in C#. You access the members of a static class by using the class name itself. ms.date: 03/15/2024 -helpviewer_keywords: +helpviewer_keywords: - "C# language, static members" - "static members [C#]" - "static classes [C#]" @@ -12,79 +12,79 @@ ms.assetid: 235614b5-1371-4dbd-9abd-b406a8b0298b --- # Static Classes and Static Class Members (C# Programming Guide) -A [static](../../language-reference/keywords/static.md) class is basically the same as a non-static class, but there's one difference: a static class can't be instantiated. In other words, you can't use the [new](../../language-reference/operators/new-operator.md) operator to create a variable of the class type. Because there's no instance variable, you access the members of a static class by using the class name itself. For example, if you have a static class that is named `UtilityClass` that has a public static method named `MethodA`, you call the method as shown in the following example: - -```csharp -UtilityClass.MethodA(); -``` - - A static class can be used as a convenient container for sets of methods that just operate on input parameters and don't have to get or set any internal instance fields. For example, in the .NET Class Library, the static class contains methods that perform mathematical operations, without any requirement to store or retrieve data that is unique to a particular instance of the class. That is, you apply the members of the class by specifying the class name and the method name, as shown in the following example. - -```csharp -double dub = -3.14; -Console.WriteLine(Math.Abs(dub)); -Console.WriteLine(Math.Floor(dub)); -Console.WriteLine(Math.Round(Math.Abs(dub))); - -// Output: -// 3.14 -// -4 -// 3 -``` - - As is the case with all class types, the .NET runtime loads the type information for a static class when the program that references the class is loaded. The program can't specify exactly when the class is loaded. However, it's guaranteed to load and have its fields initialized and its static constructor called before the class is referenced for the first time in your program. A static constructor is only called one time, and a static class remains in memory for the lifetime of the application domain in which your program resides. - +A [static](../../language-reference/keywords/static.md) class is basically the same as a non-static class, but there's one difference: a static class can't be instantiated. In other words, you can't use the [new](../../language-reference/operators/new-operator.md) operator to create a variable of the class type. Because there's no instance variable, you access the members of a static class by using the class name itself. For example, if you have a static class that is named `UtilityClass` that has a public static method named `MethodA`, you call the method as shown in the following example: + +```csharp +UtilityClass.MethodA(); +``` + + A static class can be used as a convenient container for sets of methods that just operate on input parameters and don't have to get or set any internal instance fields. For example, in the .NET Class Library, the static class contains methods that perform mathematical operations, without any requirement to store or retrieve data that is unique to a particular instance of the class. That is, you apply the members of the class by specifying the class name and the method name, as shown in the following example. + +```csharp +double dub = -3.14; +Console.WriteLine(Math.Abs(dub)); +Console.WriteLine(Math.Floor(dub)); +Console.WriteLine(Math.Round(Math.Abs(dub))); + +// Output: +// 3.14 +// -4 +// 3 +``` + + As is the case with all class types, the .NET runtime loads the type information for a static class when the program that references the class is loaded. The program can't specify exactly when the class is loaded. However, it's guaranteed to load and have its fields initialized and its static constructor called before the class is referenced for the first time in your program. A static constructor is only called one time, and a static class remains in memory for the lifetime of the application domain in which your program resides. + > [!NOTE] -> To create a non-static class that allows only one instance of itself to be created, see [Implementing Singleton in C#](/previous-versions/msp-n-p/ff650316(v=pandp.10)). - - The following list provides the main features of a static class: - -- Contains only static members. - -- Can't be instantiated. - -- Is sealed. - -- Can't contain [Instance Constructors](./instance-constructors.md). - - Creating a static class is therefore basically the same as creating a class that contains only static members and a private constructor. A private constructor prevents the class from being instantiated. The advantage of using a static class is that the compiler can check to make sure that no instance members are accidentally added. The compiler guarantees that instances of this class can't be created. - - Static classes are sealed and therefore can't be inherited. They can't inherit from any class or interface except . Static classes can't contain an instance constructor. However, they can contain a static constructor. Non-static classes should also define a static constructor if the class contains static members that require non-trivial initialization. For more information, see [Static Constructors](./static-constructors.md). - -## Example - - Here's an example of a static class that contains two methods that convert temperature from Celsius to Fahrenheit and from Fahrenheit to Celsius: - - [!code-csharp[TemperatureConverter#1](snippets/static-classes-and-static-class-members/Program.cs#1)] - -## Static Members - - A non-static class can contain static methods, fields, properties, or events. The static member is callable on a class even when no instance of the class exists. The static member is always accessed by the class name, not the instance name. Only one copy of a static member exists, regardless of how many instances of the class are created. Static methods and properties can't access non-static fields and events in their containing type, and they can't access an instance variable of any object unless it's explicitly passed in a method parameter. - - It's more typical to declare a non-static class with some static members, than to declare an entire class as static. Two common uses of static fields are to keep a count of the number of objects that are instantiated, or to store a value that must be shared among all instances. - - Static methods can be overloaded but not overridden, because they belong to the class, and not to any instance of the class. - - Although a field can't be declared as `static const`, a [const](../../language-reference/keywords/const.md) field is essentially static in its behavior. It belongs to the type, not to instances of the type. Therefore, `const` fields can be accessed by using the same `ClassName.MemberName` notation used for static fields. No object instance is required. - - C# doesn't support static local variables (that is, variables that are declared in method scope). - - You declare static class members by using the `static` keyword before the return type of the member, as shown in the following example: - - [!code-csharp[AutomobileExample#2](snippets/static-classes-and-static-class-members/Program.cs#2)] - - Static members are initialized before the static member is accessed for the first time and before the static constructor, if there's one, is called. To access a static class member, use the name of the class instead of a variable name to specify the location of the member, as shown in the following example: - - [!code-csharp[AccessingStaticMembers#3](snippets/static-classes-and-static-class-members/Program.cs#3)] - - If your class contains static fields, provide a static constructor that initializes them when the class is loaded. - - A call to a static method generates a call instruction in Microsoft intermediate language (MSIL), whereas a call to an instance method generates a `callvirt` instruction, which also checks for null object references. However, most of the time the performance difference between the two isn't significant. - -## C# Language Specification +> To create a non-static class that allows only one instance of itself to be created, see [Implementing Singleton in C#](/previous-versions/msp-n-p/ff650316(v=pandp.10)). + + The following list provides the main features of a static class: + +- Contains only static members. + +- Can't be instantiated. + +- Is sealed. + +- Can't contain [Instance Constructors](./instance-constructors.md). + + Creating a static class is therefore basically the same as creating a class that contains only static members and a private constructor. A private constructor prevents the class from being instantiated. The advantage of using a static class is that the compiler can check to make sure that no instance members are accidentally added. The compiler guarantees that instances of this class can't be created. + + Static classes are sealed and therefore can't be inherited. They can't inherit from any class or interface except . Static classes can't contain an instance constructor. However, they can contain a static constructor. Non-static classes should also define a static constructor if the class contains static members that require non-trivial initialization. For more information, see [Static Constructors](./static-constructors.md). + +## Example + + Here's an example of a static class that contains two methods that convert temperature from Celsius to Fahrenheit and from Fahrenheit to Celsius: + + [!code-csharp[TemperatureConverter#1](snippets/static-classes-and-static-class-members/Program.cs#1)] + +## Static Members + + A non-static class can contain static methods, fields, properties, or events. The static member is callable on a class even when no instance of the class exists. The static member is always accessed by the class name, not the instance name. Only one copy of a static member exists, regardless of how many instances of the class are created. Static methods and properties can't access non-static fields and events in their containing type, and they can't access an instance variable of any object unless it's explicitly passed in a method parameter. + + It's more typical to declare a non-static class with some static members, than to declare an entire class as static. Two common uses of static fields are to keep a count of the number of objects that are instantiated, or to store a value that must be shared among all instances. + + Static methods can be overloaded but not overridden, because they belong to the class, and not to any instance of the class. + + Although a field can't be declared as `static const`, a [const](../../language-reference/keywords/const.md) field is essentially static in its behavior. It belongs to the type, not to instances of the type. Therefore, `const` fields can be accessed by using the same `ClassName.MemberName` notation used for static fields. No object instance is required. + + C# doesn't support static local variables (that is, variables that are declared in method scope). + + You declare static class members by using the `static` keyword before the return type of the member, as shown in the following example: + + [!code-csharp[AutomobileExample#2](snippets/static-classes-and-static-class-members/Program.cs#2)] + + Static members are initialized before the static member is accessed for the first time and before the static constructor, if there's one, is called. To access a static class member, use the name of the class instead of a variable name to specify the location of the member, as shown in the following example: + + [!code-csharp[AccessingStaticMembers#3](snippets/static-classes-and-static-class-members/Program.cs#3)] + + If your class contains static fields, provide a static constructor that initializes them when the class is loaded. + + A call to a static method generates a call instruction in common intermediate language (CIL), whereas a call to an instance method generates a `callvirt` instruction, which also checks for null object references. However, most of the time the performance difference between the two isn't significant. + +## C# Language Specification For more information, see [Static classes](~/_csharpstandard/standard/classes.md#15224-static-classes), [Static and instance members](~/_csharpstandard/standard/classes.md#1538-static-and-instance-members) and [Static constructors](~/_csharpstandard/standard/classes.md#1512-static-constructors) in the [C# Language Specification](~/_csharpstandard/standard/README.md). The language specification is the definitive source for C# syntax and usage. - + ## See also - [static](../../language-reference/keywords/static.md) diff --git a/docs/csharp/programming-guide/concepts/iterators.md b/docs/csharp/programming-guide/concepts/iterators.md index bacdd148a3a13..aedcdc13864ad 100644 --- a/docs/csharp/programming-guide/concepts/iterators.md +++ b/docs/csharp/programming-guide/concepts/iterators.md @@ -329,7 +329,7 @@ In C#, `yield` is not a reserved word and has special meaning only when it is us Although you write an iterator as a method, the compiler translates it into a nested class that is, in effect, a state machine. This class keeps track of the position of the iterator as long the `foreach` loop in the client code continues. -To see what the compiler does, you can use the Ildasm.exe tool to view the Microsoft intermediate language code that's generated for an iterator method. +To see what the compiler does, you can use the Ildasm.exe tool to view the common intermediate language code that's generated for an iterator method. When you create an iterator for a [class](../../language-reference/keywords/class.md) or [struct](../../language-reference/builtin-types/struct.md), you don't have to implement the whole interface. When the compiler detects the iterator, it automatically generates the `Current`, `MoveNext`, and `Dispose` methods of the or interface. diff --git a/docs/csharp/programming-guide/generics/generics-in-the-run-time.md b/docs/csharp/programming-guide/generics/generics-in-the-run-time.md index 645a0580e2695..a9e4403e77167 100644 --- a/docs/csharp/programming-guide/generics/generics-in-the-run-time.md +++ b/docs/csharp/programming-guide/generics/generics-in-the-run-time.md @@ -2,48 +2,48 @@ title: "Generics in the runtime - C# Programming Guide" description: Learn about generic types in the runtime. See code examples and view additional available resources. ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "generics [C#], at run time" ms.assetid: 119df7e6-9ceb-49df-af36-24f8f8c0747f --- # Generics in the runtime (C# programming guide) -When a generic type or method is compiled into Microsoft intermediate language (MSIL), it contains metadata that identifies it as having type parameters. How the MSIL for a generic type is used differs based on whether the supplied type parameter is a value type or reference type. - - When a generic type is first constructed with a value type as a parameter, the runtime creates a specialized generic type with the supplied parameter or parameters substituted in the appropriate locations in the MSIL. Specialized generic types are created one time for each unique value type that is used as a parameter. - - For example, suppose your program code declared a stack that's constructed of integers: - +When a generic type or method is compiled into common intermediate language (CIL), it contains metadata that identifies it as having type parameters. How the CIL for a generic type is used differs based on whether the supplied type parameter is a value type or reference type. + + When a generic type is first constructed with a value type as a parameter, the runtime creates a specialized generic type with the supplied parameter or parameters substituted in the appropriate locations in the CIL. Specialized generic types are created one time for each unique value type that is used as a parameter. + + For example, suppose your program code declared a stack that's constructed of integers: + ```csharp Stack? stack; -``` - - At this point, the runtime generates a specialized version of the class that has the integer substituted appropriately for its parameter. Now, whenever your program code uses a stack of integers, the runtime reuses the generated specialized class. In the following example, two instances of a stack of integers are created, and they share a single instance of the `Stack` code: - - [!code-csharp[csProgGuideGenerics#43](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#43)] - - However, suppose that another class with a different value type such as a `long` or a user-defined structure as its parameter is created at another point in your code. As a result, the runtime generates another version of the generic type and substitutes a `long` in the appropriate locations in MSIL. Conversions are no longer necessary because each specialized generic class natively contains the value type. - - Generics work somewhat differently for reference types. The first time a generic type is constructed with any reference type, the runtime creates a specialized generic type with object references substituted for the parameters in the MSIL. Then, every time that a constructed type is instantiated with a reference type as its parameter, regardless of what type it is, the runtime reuses the previously created specialized version of the generic type. This is possible because all references are the same size. - - For example, suppose you had two reference types, a `Customer` class and an `Order` class, and also suppose that you created a stack of `Customer` types: - - [!code-csharp[csProgGuideGenerics#47](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#47)] - - [!code-csharp[csProgGuideGenerics#44](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#44)] - - At this point, the runtime generates a specialized version of the class that stores object references that will be filled in later instead of storing data. Suppose the next line of code creates a stack of another reference type, which is named `Order`: - - [!code-csharp[csProgGuideGenerics#45](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#45)] - - Unlike with value types, another specialized version of the class is not created for the `Order` type. Instead, an instance of the specialized version of the class is created and the `orders` variable is set to reference it. Suppose that you then encountered a line of code to create a stack of a `Customer` type: - - [!code-csharp[csProgGuideGenerics#46](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#46)] - - As with the previous use of the class created by using the `Order` type, another instance of the specialized class is created. The pointers that are contained therein are set to reference an area of memory the size of a `Customer` type. Because the number of reference types can vary wildly from program to program, the C# implementation of generics greatly reduces the amount of code by reducing to one the number of specialized classes created by the compiler for generic classes of reference types. - - Moreover, when a generic C# class is instantiated by using a value type or reference type parameter, reflection can query it at run time and both its actual type and its type parameter can be ascertained. - +``` + + At this point, the runtime generates a specialized version of the class that has the integer substituted appropriately for its parameter. Now, whenever your program code uses a stack of integers, the runtime reuses the generated specialized class. In the following example, two instances of a stack of integers are created, and they share a single instance of the `Stack` code: + + [!code-csharp[csProgGuideGenerics#43](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#43)] + + However, suppose that another class with a different value type such as a `long` or a user-defined structure as its parameter is created at another point in your code. As a result, the runtime generates another version of the generic type and substitutes a `long` in the appropriate locations in CIL. Conversions are no longer necessary because each specialized generic class natively contains the value type. + + Generics work somewhat differently for reference types. The first time a generic type is constructed with any reference type, the runtime creates a specialized generic type with object references substituted for the parameters in the CIL. Then, every time that a constructed type is instantiated with a reference type as its parameter, regardless of what type it is, the runtime reuses the previously created specialized version of the generic type. This is possible because all references are the same size. + + For example, suppose you had two reference types, a `Customer` class and an `Order` class, and also suppose that you created a stack of `Customer` types: + + [!code-csharp[csProgGuideGenerics#47](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#47)] + + [!code-csharp[csProgGuideGenerics#44](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#44)] + + At this point, the runtime generates a specialized version of the class that stores object references that will be filled in later instead of storing data. Suppose the next line of code creates a stack of another reference type, which is named `Order`: + + [!code-csharp[csProgGuideGenerics#45](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#45)] + + Unlike with value types, another specialized version of the class is not created for the `Order` type. Instead, an instance of the specialized version of the class is created and the `orders` variable is set to reference it. Suppose that you then encountered a line of code to create a stack of a `Customer` type: + + [!code-csharp[csProgGuideGenerics#46](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#46)] + + As with the previous use of the class created by using the `Order` type, another instance of the specialized class is created. The pointers that are contained therein are set to reference an area of memory the size of a `Customer` type. Because the number of reference types can vary wildly from program to program, the C# implementation of generics greatly reduces the amount of code by reducing to one the number of specialized classes created by the compiler for generic classes of reference types. + + Moreover, when a generic C# class is instantiated by using a value type or reference type parameter, reflection can query it at run time and both its actual type and its type parameter can be ascertained. + ## See also - diff --git a/docs/framework/64-bit-apps.md b/docs/framework/64-bit-apps.md index 8aeffa7258639..e56c6674bd1c5 100644 --- a/docs/framework/64-bit-apps.md +++ b/docs/framework/64-bit-apps.md @@ -2,7 +2,7 @@ title: "64-bit Applications" description: Get information about configuring applications on a Windows 64-bit OS, as either a native 64-bit application or under WOW64 (Windows 32-bit on Windows 64-bit). ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "applications [C++], 64-bit" - "64-bit applications [C++]" - "64-bit programming [C++]" @@ -10,51 +10,51 @@ ms.assetid: fd4026bc-2c3d-4b27-86dc-ec5e96018181 --- # 64-bit Applications -When you compile an application, you can specify that it should run on a Windows 64-bit operating system either as a native application or under WOW64 (Windows 32-bit on Windows 64-bit). WOW64 is a compatibility environment that enables a 32-bit application to run on a 64-bit system. WOW64 is included in all 64-bit versions of the Windows operating system. - -## Running 32-bit vs. 64-bit Applications on Windows +When you compile an application, you can specify that it should run on a Windows 64-bit operating system either as a native application or under WOW64 (Windows 32-bit on Windows 64-bit). WOW64 is a compatibility environment that enables a 32-bit application to run on a 64-bit system. WOW64 is included in all 64-bit versions of the Windows operating system. + +## Running 32-bit vs. 64-bit Applications on Windows + + All applications that are built on the .NET Framework 1.0 or 1.1 are treated as 32-bit applications on a 64-bit operating system and are always executed under WOW64 and the 32-bit common language runtime (CLR). 32-bit applications that are built on the .NET Framework 4 or later versions also run under WOW64 on 64-bit systems. + + Visual Studio installs the 32-bit version of the CLR on an x86 computer, and both the 32-bit version and the appropriate 64-bit version of the CLR on a 64-bit Windows computer. (Because Visual Studio is a 32-bit application, when it is installed on a 64-bit system, it runs under WOW64.) - All applications that are built on the .NET Framework 1.0 or 1.1 are treated as 32-bit applications on a 64-bit operating system and are always executed under WOW64 and the 32-bit common language runtime (CLR). 32-bit applications that are built on the .NET Framework 4 or later versions also run under WOW64 on 64-bit systems. - - Visual Studio installs the 32-bit version of the CLR on an x86 computer, and both the 32-bit version and the appropriate 64-bit version of the CLR on a 64-bit Windows computer. (Because Visual Studio is a 32-bit application, when it is installed on a 64-bit system, it runs under WOW64.) - > [!NOTE] -> Because of the design of x86 emulation and the WOW64 subsystem for the Itanium processor family, applications are restricted to execution on one processor. These factors reduce the performance and scalability of 32-bit .NET Framework applications that run on Itanium-based systems. We recommend that you use the .NET Framework 4, which includes native 64-bit support for Itanium-based systems, for increased performance and scalability. - - By default, when you run a 64-bit managed application on a 64-bit Windows operating system, you can create an object of no more than 2 gigabytes (GB). However, in .NET Framework 4.5, you can increase this limit. For more information, see the [\ element](./configure-apps/file-schema/runtime/gcallowverylargeobjects-element.md). - - Many assemblies run identically on both the 32-bit CLR and the 64-bit CLR. However, some programs may behave differently, depending on the CLR, if they contain one or more of the following: - -- Structures that contain members that change size depending on the platform (for example, any pointer type). - -- Pointer arithmetic that includes constant sizes. - -- Incorrect platform invoke or COM declarations that use `Int32` for handles instead of `IntPtr`. - -- Code that casts `IntPtr` to `Int32`. - - For more information about how to port a 32-bit application to run on the 64-bit CLR, see [Migrating 32-bit Managed Code to 64-bit](/previous-versions/dotnet/articles/ms973190(v=msdn.10)). - -## General 64-Bit Programming Information - - For general information about 64-bit programming, see the following documents: - -- In the Windows SDK documentation, see [Programming Guide for 64-bit Windows](/windows/win32/winprog64/programming-guide-for-64-bit-windows). - -- For information about Visual Studio support for creating 64-bit applications, see [Visual Studio IDE 64-Bit Support](/visualstudio/ide/visual-studio-ide-64-bit-support). - -## Compiler Support for Creating 64-Bit Applications - - By default, when you use the .NET Framework to build an application on either a 32-bit or a 64-bit computer, the application will run on a 64-bit computer as a native application (that is, not under WOW64). The following table lists documents that explain how to use Visual Studio compilers to create 64-bit applications that will run as native, under WOW64, or both. - -|Compiler|Compiler option| -|--------------|---------------------| -|Visual Basic|[-platform (Visual Basic)](../visual-basic/reference/command-line-compiler/platform.md)| -|Visual C#|[-platform (C# Compiler Options)](../csharp/language-reference/compiler-options/output.md#platformtarget)| -|Visual C++|You can create platform-agnostic, Microsoft intermediate language (MSIL) applications by using **/clr:safe**. For more information, see [-clr (Common Language Runtime Compilation)](/cpp/build/reference/clr-common-language-runtime-compilation).

Visual C++ includes a separate compiler for each 64-bit operating system. For more information about how to use Visual C++ to create native applications that run on a 64-bit Windows operating system, see [64-bit Programming](/cpp/build/configuring-programs-for-64-bit-visual-cpp).| - -## Determining the Status of an .exe File or .dll File - - To determine whether an .exe file or .dll file is meant to run only on a specific platform or under WOW64, use [CorFlags.exe (CorFlags Conversion Tool)](./tools/corflags-exe-corflags-conversion-tool.md) with no options. You can also use CorFlags.exe to change the platform status of an .exe file or .dll file. The CLR header of a Visual Studio assembly has the major runtime version number set to 2 and the minor runtime version number set to 5. Applications that have the minor runtime version set to 0 are treated as legacy applications and are always executed under WOW64. - +> Because of the design of x86 emulation and the WOW64 subsystem for the Itanium processor family, applications are restricted to execution on one processor. These factors reduce the performance and scalability of 32-bit .NET Framework applications that run on Itanium-based systems. We recommend that you use the .NET Framework 4, which includes native 64-bit support for Itanium-based systems, for increased performance and scalability. + + By default, when you run a 64-bit managed application on a 64-bit Windows operating system, you can create an object of no more than 2 gigabytes (GB). However, in .NET Framework 4.5, you can increase this limit. For more information, see the [\ element](./configure-apps/file-schema/runtime/gcallowverylargeobjects-element.md). + + Many assemblies run identically on both the 32-bit CLR and the 64-bit CLR. However, some programs may behave differently, depending on the CLR, if they contain one or more of the following: + +- Structures that contain members that change size depending on the platform (for example, any pointer type). + +- Pointer arithmetic that includes constant sizes. + +- Incorrect platform invoke or COM declarations that use `Int32` for handles instead of `IntPtr`. + +- Code that casts `IntPtr` to `Int32`. + + For more information about how to port a 32-bit application to run on the 64-bit CLR, see [Migrating 32-bit Managed Code to 64-bit](/previous-versions/dotnet/articles/ms973190(v=msdn.10)). + +## General 64-Bit Programming Information + + For general information about 64-bit programming, see the following documents: + +- In the Windows SDK documentation, see [Programming Guide for 64-bit Windows](/windows/win32/winprog64/programming-guide-for-64-bit-windows). + +- For information about Visual Studio support for creating 64-bit applications, see [Visual Studio IDE 64-Bit Support](/visualstudio/ide/visual-studio-ide-64-bit-support). + +## Compiler Support for Creating 64-Bit Applications + + By default, when you use the .NET Framework to build an application on either a 32-bit or a 64-bit computer, the application will run on a 64-bit computer as a native application (that is, not under WOW64). The following table lists documents that explain how to use Visual Studio compilers to create 64-bit applications that will run as native, under WOW64, or both. + +|Compiler|Compiler option| +|--------------|---------------------| +|Visual Basic|[-platform (Visual Basic)](../visual-basic/reference/command-line-compiler/platform.md)| +|Visual C#|[-platform (C# Compiler Options)](../csharp/language-reference/compiler-options/output.md#platformtarget)| +|Visual C++|You can create platform-agnostic, common intermediate language (CIL) applications by using **/clr:safe**. For more information, see [-clr (Common Language Runtime Compilation)](/cpp/build/reference/clr-common-language-runtime-compilation).

Visual C++ includes a separate compiler for each 64-bit operating system. For more information about how to use Visual C++ to create native applications that run on a 64-bit Windows operating system, see [64-bit Programming](/cpp/build/configuring-programs-for-64-bit-visual-cpp).| + +## Determining the Status of an .exe File or .dll File + + To determine whether an .exe file or .dll file is meant to run only on a specific platform or under WOW64, use [CorFlags.exe (CorFlags Conversion Tool)](./tools/corflags-exe-corflags-conversion-tool.md) with no options. You can also use CorFlags.exe to change the platform status of an .exe file or .dll file. The CLR header of a Visual Studio assembly has the major runtime version number set to 2 and the minor runtime version number set to 5. Applications that have the minor runtime version set to 0 are treated as legacy applications and are always executed under WOW64. + To programmatically query an .exe or .dll to see whether it is meant to run only on a specific platform or under WOW64, use the method. diff --git a/docs/framework/app-domains/build-multifile-assembly.md b/docs/framework/app-domains/build-multifile-assembly.md index 38281dbd59713..d0168cb754e87 100644 --- a/docs/framework/app-domains/build-multifile-assembly.md +++ b/docs/framework/app-domains/build-multifile-assembly.md @@ -215,7 +215,7 @@ This article explains how to create a multifile assembly and provides code that al Client.netmodule Stringer.netmodule /main:MainClientApp.Main /out:myAssembly.exe /target:exe ``` - You can use the [MSIL Disassembler (Ildasm.exe)](../tools/ildasm-exe-il-disassembler.md) to examine the contents of an assembly, or determine whether a file is an assembly or a module. + You can use [IL Disassembler (Ildasm.exe)](../tools/ildasm-exe-il-disassembler.md) to examine the contents of an assembly, or determine whether a file is an assembly or a module. ## See also diff --git a/docs/framework/app-domains/working-with-assemblies-and-the-gac.md b/docs/framework/app-domains/working-with-assemblies-and-the-gac.md index 75742240fcca1..d9b12e27bd732 100644 --- a/docs/framework/app-domains/working-with-assemblies-and-the-gac.md +++ b/docs/framework/app-domains/working-with-assemblies-and-the-gac.md @@ -2,7 +2,7 @@ title: "Working with Assemblies and the Global Assembly Cache" description: Work with assemblies and the global assembly cache (GAC) in .NET. Review the reasons why you might want to install an assembly in the GAC. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "assemblies [.NET Framework], global assembly cache" - "global assembly cache, benefits" - "ACLs [.NET Framework]" @@ -12,60 +12,60 @@ ms.assetid: 8a18e5c2-d41d-49ef-abcb-7c27e2469433 --- # Working with Assemblies and the Global Assembly Cache -If you intend to share an assembly among several applications, you can install it into the global assembly cache. Each computer where the common language runtime is installed has this machine-wide code cache. The global assembly cache stores assemblies specifically designated to be shared by several applications on the computer. An assembly must have a strong name to be installed in the global assembly cache. - +If you intend to share an assembly among several applications, you can install it into the global assembly cache. Each computer where the common language runtime is installed has this machine-wide code cache. The global assembly cache stores assemblies specifically designated to be shared by several applications on the computer. An assembly must have a strong name to be installed in the global assembly cache. + > [!NOTE] -> Assemblies placed in the global assembly cache must have the same assembly name and file name (not including the file name extension). For example, an assembly with the assembly name of myAssembly must have a file name of either myAssembly.exe or myAssembly.dll. - -You should share assemblies by installing them into the global assembly cache only when necessary. As a general guideline, keep assembly dependencies private and locate assemblies in the application directory unless sharing an assembly is explicitly required. In addition, you do not have to install assemblies into the global assembly cache to make them accessible to COM interop or unmanaged code. - -There are several reasons why you might want to install an assembly into the global assembly cache: - -- Shared location. - - Assemblies that should be used by applications can be put in the global assembly cache. For example, if all applications should use an assembly located in the global assembly cache, a version policy statement can be added to the Machine.config file that redirects references to the assembly. - -- File security. - - Administrators often protect the systemroot directory using an Access Control List (ACL) to control write and execute access. Because the global assembly cache is installed in the systemroot directory, it inherits that directory's ACL. It is recommended that only users with Administrator privileges be allowed to delete files from the global assembly cache. - -- Side-by-side versioning. - - Multiple copies of assemblies with the same name but different version information can be maintained in the global assembly cache. - -- Additional search location. - - The common language runtime checks the global assembly cache for an assembly that matches the assembly request before probing or using the codebase information in a configuration file. - - Note that there are scenarios where you explicitly do not want to install an assembly into the global assembly cache. If you place one of the assemblies that make up an application into the global assembly cache, you can no longer replicate or install the application by using XCOPY to copy the application directory. In this case, you must also move the assembly into the global assembly cache. - -## In This Section - -[How to: Install an Assembly into the Global Assembly Cache](install-assembly-into-gac.md) -Describes the ways to install an assembly into the global assembly cache. - -[How to: View the Contents of the Global Assembly Cache](how-to-view-the-contents-of-the-gac.md) -Explains how to use the [Gacutil.exe (Global Assembly Cache Tool)](../tools/gacutil-exe-gac-tool.md) to view the contents of the global assembly cache. - -[How to: Remove an Assembly from the Global Assembly Cache](how-to-remove-an-assembly-from-the-gac.md) -Explains how to use the [Gacutil.exe (Global Assembly Cache Tool)](../tools/gacutil-exe-gac-tool.md) to remove an assembly from the global assembly cache. - -[Using Serviced Components with the Global Assembly Cache](use-serviced-components-with-the-gac.md) -Explains why serviced components (managed COM+ components) should be placed in the global assembly cache. - -## Related Sections - -[Creating Assemblies](../../standard/assembly/create.md) -Provides an overview of creating assemblies. - -[Global Assembly Cache](gac.md) -Describes the global assembly cache. - -[How to: View Assembly Contents](../../standard/assembly/view-contents.md) -Explains how to use the [Ildasm.exe (IL Disassembler)](../tools/ildasm-exe-il-disassembler.md) to view Microsoft intermediate language (MSIL) information in an assembly. - -[How the Runtime Locates Assemblies](../deployment/how-the-runtime-locates-assemblies.md) -Describes how the common language runtime locates and loads the assemblies that make up your application. - -[Programming with Assemblies](../../standard/assembly/index.md) +> Assemblies placed in the global assembly cache must have the same assembly name and file name (not including the file name extension). For example, an assembly with the assembly name of myAssembly must have a file name of either myAssembly.exe or myAssembly.dll. + +You should share assemblies by installing them into the global assembly cache only when necessary. As a general guideline, keep assembly dependencies private and locate assemblies in the application directory unless sharing an assembly is explicitly required. In addition, you do not have to install assemblies into the global assembly cache to make them accessible to COM interop or unmanaged code. + +There are several reasons why you might want to install an assembly into the global assembly cache: + +- Shared location. + + Assemblies that should be used by applications can be put in the global assembly cache. For example, if all applications should use an assembly located in the global assembly cache, a version policy statement can be added to the Machine.config file that redirects references to the assembly. + +- File security. + + Administrators often protect the systemroot directory using an Access Control List (ACL) to control write and execute access. Because the global assembly cache is installed in the systemroot directory, it inherits that directory's ACL. It is recommended that only users with Administrator privileges be allowed to delete files from the global assembly cache. + +- Side-by-side versioning. + + Multiple copies of assemblies with the same name but different version information can be maintained in the global assembly cache. + +- Additional search location. + + The common language runtime checks the global assembly cache for an assembly that matches the assembly request before probing or using the codebase information in a configuration file. + + Note that there are scenarios where you explicitly do not want to install an assembly into the global assembly cache. If you place one of the assemblies that make up an application into the global assembly cache, you can no longer replicate or install the application by using XCOPY to copy the application directory. In this case, you must also move the assembly into the global assembly cache. + +## In This Section + +[How to: Install an Assembly into the Global Assembly Cache](install-assembly-into-gac.md) +Describes the ways to install an assembly into the global assembly cache. + +[How to: View the Contents of the Global Assembly Cache](how-to-view-the-contents-of-the-gac.md) +Explains how to use the [Gacutil.exe (Global Assembly Cache Tool)](../tools/gacutil-exe-gac-tool.md) to view the contents of the global assembly cache. + +[How to: Remove an Assembly from the Global Assembly Cache](how-to-remove-an-assembly-from-the-gac.md) +Explains how to use the [Gacutil.exe (Global Assembly Cache Tool)](../tools/gacutil-exe-gac-tool.md) to remove an assembly from the global assembly cache. + +[Using Serviced Components with the Global Assembly Cache](use-serviced-components-with-the-gac.md) +Explains why serviced components (managed COM+ components) should be placed in the global assembly cache. + +## Related Sections + +[Creating Assemblies](../../standard/assembly/create.md) +Provides an overview of creating assemblies. + +[Global Assembly Cache](gac.md) +Describes the global assembly cache. + +[How to: View Assembly Contents](../../standard/assembly/view-contents.md) +Explains how to use the [Ildasm.exe (IL Disassembler)](../tools/ildasm-exe-il-disassembler.md) to view common intermediate language (CIL) information in an assembly. + +[How the Runtime Locates Assemblies](../deployment/how-the-runtime-locates-assemblies.md) +Describes how the common language runtime locates and loads the assemblies that make up your application. + +[Programming with Assemblies](../../standard/assembly/index.md) Describes assemblies, the building blocks of managed applications. diff --git a/docs/framework/data/adonet/protecting-connection-information.md b/docs/framework/data/adonet/protecting-connection-information.md index 857fe79b25c1d..20370268dc431 100644 --- a/docs/framework/data/adonet/protecting-connection-information.md +++ b/docs/framework/data/adonet/protecting-connection-information.md @@ -6,40 +6,40 @@ ms.assetid: 1471f580-bcd4-4046-bdaf-d2541ecda2f4 --- # Protecting Connection Information -Protecting access to your data source is one of the most important goals when securing an application. A connection string presents a potential vulnerability if it is not secured. Storing connection information in plain text or persisting it in memory risks compromising your entire system. Connection strings embedded in your source code can be read using the [Ildasm.exe (IL Disassembler)](../../tools/ildasm-exe-il-disassembler.md) to view Microsoft intermediate language (MSIL) in a compiled assembly. - - Security vulnerabilities involving connection strings can arise based on the type of authentication used, how connection strings are persisted in memory and on disk, and the techniques used to construct them at run time. - -## Use Windows Authentication - - To help limit access to your data source, you must secure connection information such as user ID, password, and data source name. In order to avoid exposing user information, we recommend using Windows authentication (sometimes referred to as *integrated security*) wherever possible. Windows authentication is specified in a connection string by using the `Integrated Security` or `Trusted_Connection` keywords, eliminating the need to use a user ID and password. When using Windows authentication, users are authenticated by Windows, and access to server and database resources is determined by granting permissions to Windows users and groups. - - For situations where it is not possible to use Windows authentication, you must use extra care because user credentials are exposed in the connection string. In an ASP.NET application, you can configure a Windows account as a fixed identity that is used to connect to databases and other network resources. You enable impersonation in the identity element in the **web.config** file and specify a user name and password. - -```xml +Protecting access to your data source is one of the most important goals when securing an application. A connection string presents a potential vulnerability if it is not secured. Storing connection information in plain text or persisting it in memory risks compromising your entire system. Connection strings embedded in your source code can be read using the [Ildasm.exe (IL Disassembler)](../../tools/ildasm-exe-il-disassembler.md) to view common intermediate language (CIL) in a compiled assembly. + + Security vulnerabilities involving connection strings can arise based on the type of authentication used, how connection strings are persisted in memory and on disk, and the techniques used to construct them at run time. + +## Use Windows Authentication + + To help limit access to your data source, you must secure connection information such as user ID, password, and data source name. In order to avoid exposing user information, we recommend using Windows authentication (sometimes referred to as *integrated security*) wherever possible. Windows authentication is specified in a connection string by using the `Integrated Security` or `Trusted_Connection` keywords, eliminating the need to use a user ID and password. When using Windows authentication, users are authenticated by Windows, and access to server and database resources is determined by granting permissions to Windows users and groups. + + For situations where it is not possible to use Windows authentication, you must use extra care because user credentials are exposed in the connection string. In an ASP.NET application, you can configure a Windows account as a fixed identity that is used to connect to databases and other network resources. You enable impersonation in the identity element in the **web.config** file and specify a user name and password. + +```xml -``` - - The fixed identity account should be a low-privilege account that has been granted only necessary permissions in the database. In addition, you should encrypt the configuration file so that the user name and password are not exposed in clear text. - -## Do Not Use Universal Data Link (UDL) files - - Avoid storing connection strings for an in a Universal Data Link (UDL) file. UDLs are stored in clear text and cannot be encrypted. A UDL file is an external file-based resource to your application, and it cannot be secured or encrypted using the .NET Framework. - -## Avoid Injection Attacks with Connection String Builders - - A connection string injection attack can occur when dynamic string concatenation is used to build connection strings based on user input. If the user input is not validated and malicious text or characters not escaped, an attacker can potentially access sensitive data or other resources on the server. To address this problem, ADO.NET 2.0 introduced new connection string builder classes to validate connection string syntax and ensure that additional parameters are not introduced. For more information, see [Connection String Builders](connection-string-builders.md). - -## Use Persist Security Info=False - - The default value for `Persist Security Info` is false; we recommend using this default in all connection strings. Setting `Persist Security Info` to `true` or `yes` allows security-sensitive information, including the user ID and password, to be obtained from a connection after it has been opened. When `Persist Security Info` is set to `false` or `no`, security information is discarded after it is used to open the connection, ensuring that an untrusted source does not have access to security-sensitive information. - -## Encrypt Configuration Files - - You can also store connection strings in configuration files, which eliminates the need to embed them in your application's code. Configuration files are standard XML files for which the .NET Framework has defined a common set of elements. Connection strings in configuration files are typically stored inside the **\** element in the **app.config** for a Windows application, or the **web.config** file for an ASP.NET application. For more information on the basics of storing, retrieving and encrypting connection strings from configuration files, see [Connection Strings and Configuration Files](connection-strings-and-configuration-files.md). - + password="*****" /> +``` + + The fixed identity account should be a low-privilege account that has been granted only necessary permissions in the database. In addition, you should encrypt the configuration file so that the user name and password are not exposed in clear text. + +## Do Not Use Universal Data Link (UDL) files + + Avoid storing connection strings for an in a Universal Data Link (UDL) file. UDLs are stored in clear text and cannot be encrypted. A UDL file is an external file-based resource to your application, and it cannot be secured or encrypted using the .NET Framework. + +## Avoid Injection Attacks with Connection String Builders + + A connection string injection attack can occur when dynamic string concatenation is used to build connection strings based on user input. If the user input is not validated and malicious text or characters not escaped, an attacker can potentially access sensitive data or other resources on the server. To address this problem, ADO.NET 2.0 introduced new connection string builder classes to validate connection string syntax and ensure that additional parameters are not introduced. For more information, see [Connection String Builders](connection-string-builders.md). + +## Use Persist Security Info=False + + The default value for `Persist Security Info` is false; we recommend using this default in all connection strings. Setting `Persist Security Info` to `true` or `yes` allows security-sensitive information, including the user ID and password, to be obtained from a connection after it has been opened. When `Persist Security Info` is set to `false` or `no`, security information is discarded after it is used to open the connection, ensuring that an untrusted source does not have access to security-sensitive information. + +## Encrypt Configuration Files + + You can also store connection strings in configuration files, which eliminates the need to embed them in your application's code. Configuration files are standard XML files for which the .NET Framework has defined a common set of elements. Connection strings in configuration files are typically stored inside the **\** element in the **app.config** for a Windows application, or the **web.config** file for an ASP.NET application. For more information on the basics of storing, retrieving and encrypting connection strings from configuration files, see [Connection Strings and Configuration Files](connection-strings-and-configuration-files.md). + ## See also - [Securing ADO.NET Applications](securing-ado-net-applications.md) diff --git a/docs/framework/debug-trace-profile/code-contracts.md b/docs/framework/debug-trace-profile/code-contracts.md index d75aaa749b383..48ef0d8a7176b 100644 --- a/docs/framework/debug-trace-profile/code-contracts.md +++ b/docs/framework/debug-trace-profile/code-contracts.md @@ -29,7 +29,7 @@ The benefits of code contracts include the following: - Reference documentation: The documentation generator augments existing XML documentation files with contract information. There are also style sheets that can be used with [Sandcastle](https://github.com/EWSoftware/SHFB) so that the generated documentation pages have contract sections. -All .NET Framework languages can immediately take advantage of contracts; you do not have to write a special parser or compiler. A Visual Studio add-in lets you specify the level of code contract analysis to be performed. The analyzers can confirm that the contracts are well-formed (type checking and name resolution) and can produce a compiled form of the contracts in Microsoft intermediate language (MSIL) format. Authoring contracts in Visual Studio lets you take advantage of the standard IntelliSense provided by the tool. +All .NET Framework languages can immediately take advantage of contracts; you do not have to write a special parser or compiler. A Visual Studio add-in lets you specify the level of code contract analysis to be performed. The analyzers can confirm that the contracts are well-formed (type checking and name resolution) and can produce a compiled form of the contracts in common intermediate language (CIL) format. Authoring contracts in Visual Studio lets you take advantage of the standard IntelliSense provided by the tool. Most methods in the contract class are conditionally compiled; that is, the compiler emits calls to these methods only when you define a special symbol, CONTRACTS_FULL, by using the `#define` directive. CONTRACTS_FULL lets you write contracts in your code without using `#ifdef` directives; you can produce different builds, some with contracts, and some without. diff --git a/docs/framework/debug-trace-profile/index.md b/docs/framework/debug-trace-profile/index.md index ffb77c4711a62..85d24f3c1c6a1 100644 --- a/docs/framework/debug-trace-profile/index.md +++ b/docs/framework/debug-trace-profile/index.md @@ -2,7 +2,7 @@ title: "Debugging, Tracing, and Profiling" description: Read about debugging, tracing, and profiling in .NET. See articles covering just-in-time (JIT) debugging, tracing and instrumenting applications, and more. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "debugging [.NET Framework]" - ".NET Framework application configuration, debugging" - "debugging [.NET Framework], .NET Framework application debugging" @@ -17,24 +17,24 @@ ms.assetid: 4a04863e-2475-46f4-bc3f-3c11510c2a4b --- # Debugging, tracing, and profiling -To debug a .NET Framework application, the compiler and runtime environment must be configured to enable a debugger to attach to the application and to produce both symbols and line maps, if possible, for the application and its corresponding Microsoft intermediate language (MSIL). After a managed application has been debugged, it can be profiled to boost performance. Profiling evaluates and describes the lines of source code that generate the most frequently executed code, and how much time it takes to execute them. - - .NET Framework applications are easily debugged by using Visual Studio, which handles many of the configuration details. If Visual Studio is not installed, you can examine and improve the performance of .NET Framework applications by using the debugging classes in the .NET Framework namespace. This namespace includes the , , and classes for tracing execution flow, and the , , and classes for profiling code. - -## In this section +To debug a .NET Framework application, the compiler and runtime environment must be configured to enable a debugger to attach to the application and to produce both symbols and line maps, if possible, for the application and its corresponding common intermediate language (CIL). After a managed application has been debugged, it can be profiled to boost performance. Profiling evaluates and describes the lines of source code that generate the most frequently executed code, and how much time it takes to execute them. + + .NET Framework applications are easily debugged by using Visual Studio, which handles many of the configuration details. If Visual Studio is not installed, you can examine and improve the performance of .NET Framework applications by using the debugging classes in the .NET Framework namespace. This namespace includes the , , and classes for tracing execution flow, and the , , and classes for profiling code. + +## In this section [Enabling JIT-Attach Debugging](enabling-jit-attach-debugging.md)\ -Shows how to configure the registry to JIT-attach a debug engine to a .NET Framework application. - +Shows how to configure the registry to JIT-attach a debug engine to a .NET Framework application. + [Making an Image Easier to Debug](making-an-image-easier-to-debug.md)\ -Shows how to turn JIT tracking on and optimization off to make an assembly easier to debug. - +Shows how to turn JIT tracking on and optimization off to make an assembly easier to debug. + [Tracing and Instrumenting Applications](tracing-and-instrumenting-applications.md)\ -Describes how to monitor the execution of your application while it is running, and how to instrument it to display how well it is performing or whether something has gone wrong. - +Describes how to monitor the execution of your application while it is running, and how to instrument it to display how well it is performing or whether something has gone wrong. + [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md)\ -Describes managed debugging assistants (MDAs), which are debugging aids that work in conjunction with the common language runtime (CLR) to provide information on runtime state. - +Describes managed debugging assistants (MDAs), which are debugging aids that work in conjunction with the common language runtime (CLR) to provide information on runtime state. + [Enhancing Debugging with the Debugger Display Attributes](enhancing-debugging-with-the-debugger-display-attributes.md)\ Describes how the developer of a type can specify what that type will look like when it is displayed in a debugger. @@ -42,12 +42,12 @@ Describes how the developer of a type can specify what that type will look like Learn how to gather information about application performance. [Performance Counters](performance-counters.md)\ -Describes the counters that you can use to track the performance of an application. - -## Related sections - -[Debug ASP.NET or ASP.NET Core apps in Visual Studio](/visualstudio/debugger/how-to-enable-debugging-for-aspnet-applications) -Provides prerequisites and instructions for how to debug an ASP.NET application during development or after deployment. - -[Development Guide](../development-guide.md) +Describes the counters that you can use to track the performance of an application. + +## Related sections + +[Debug ASP.NET or ASP.NET Core apps in Visual Studio](/visualstudio/debugger/how-to-enable-debugging-for-aspnet-applications) +Provides prerequisites and instructions for how to debug an ASP.NET application during development or after deployment. + +[Development Guide](../development-guide.md) Provides a guide to all key technology areas and tasks for application development, including creating, configuring, debugging, securing, and deploying your application, and information about dynamic programming, interoperability, extensibility, memory management, and threading. diff --git a/docs/framework/debug-trace-profile/making-an-image-easier-to-debug.md b/docs/framework/debug-trace-profile/making-an-image-easier-to-debug.md index e2a5c3efa3b45..76480957db375 100644 --- a/docs/framework/debug-trace-profile/making-an-image-easier-to-debug.md +++ b/docs/framework/debug-trace-profile/making-an-image-easier-to-debug.md @@ -13,15 +13,15 @@ ms.assetid: 7d90ea7a-150f-4f97-98a7-f9c26541b9a3 When compiling unmanaged code, you can configure an executable image for debugging by setting IDE switches or command-line options. For example, you can use the /**Zi** command-line option in Visual C++ to ask it to emit debug symbol files (file extension .pdb). Similarly, the /**Od** command-line option tells the compiler to disable optimization. The resulting code runs more slowly, but it's easier to debug, should this be necessary. -When compiling .NET Framework managed code, compilers such as Visual C++, Visual Basic, and C# compile their source program into Microsoft intermediate language (MSIL). MSIL is then JIT-compiled, just before execution, into native machine code. As with unmanaged code, you can configure an executable image for debugging by setting IDE switches or command-line options. You can also configure the JIT compilation for debugging in much the same way. +When compiling .NET Framework managed code, compilers such as Visual C++, Visual Basic, and C# compile their source program into common intermediate language (CIL). CIL is then JIT-compiled, just before execution, into native machine code. As with unmanaged code, you can configure an executable image for debugging by setting IDE switches or command-line options. You can also configure the JIT compilation for debugging in much the same way. This JIT configuration has two aspects: -- You can request the JIT compiler to generate tracking information. This makes it possible for the debugger to match up a chain of MSIL with its machine code counterpart, and to track where local variables and function arguments are stored. In .NET Framework version 2.0 and later, the JIT compiler always generates tracking information, so there's no need to request it. +- You can request the JIT compiler to generate tracking information. This makes it possible for the debugger to match up a chain of CIL with its machine code counterpart, and to track where local variables and function arguments are stored. In .NET Framework version 2.0 and later, the JIT compiler always generates tracking information, so there's no need to request it. - You can request the JIT compiler to not optimize the resulting machine code. -Normally, the compiler that generates the MSIL sets these JIT compiler options appropriately, based upon the IDE switches or command-line options you specify, for example, /**Od**. +Normally, the compiler that generates the CIL sets these JIT compiler options appropriately, based upon the IDE switches or command-line options you specify, for example, /**Od**. In some cases, you might want to change the behavior of the JIT compiler so that the machine code it generates is easier to debug. For example, you might want to generate JIT tracking information for a retail build or control optimization. You can do so with an initialization (.ini) file. diff --git a/docs/framework/debug-trace-profile/performance-counters.md b/docs/framework/debug-trace-profile/performance-counters.md index 3b456a7b83fb8..4ab462a627fab 100644 --- a/docs/framework/debug-trace-profile/performance-counters.md +++ b/docs/framework/debug-trace-profile/performance-counters.md @@ -43,12 +43,12 @@ The *.NET CLR JIT* category includes counters that provide information about cod |Performance counter|Description| |-------------------------|-----------------| -|**# of IL Bytes JITted**|Displays the total number of Microsoft intermediate language (MSIL) bytes compiled by the just-in-time (JIT) compiler since the application started. This counter is equivalent to the **Total # of IL Bytes Jitted** counter.| +|**# of IL Bytes JITted**|Displays the total number of common intermediate language (CIL) bytes compiled by the just-in-time (JIT) compiler since the application started. This counter is equivalent to the **Total # of IL Bytes Jitted** counter.| |**# of Methods JITted**|Displays the total number of methods JIT-compiled since the application started. This counter does not include pre-JIT-compiled methods.| |**% Time in Jit**|Displays the percentage of elapsed time spent in JIT compilation since the last JIT compilation phase. This counter is updated at the end of every JIT compilation phase. A JIT compilation phase occurs when a method and its dependencies are compiled.| -|**IL Bytes Jitted / sec**|Displays the number of MSIL bytes that are JIT-compiled per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Standard Jit Failures**|Displays the peak number of methods the JIT compiler has failed to compile since the application started. This failure can occur if the MSIL cannot be verified or if there is an internal error in the JIT compiler.| -|**Total # of IL Bytes Jitted**|Displays the total MSIL bytes JIT-compiled since the application started. This counter is equivalent to the **# of IL Bytes Jitted** counter.| +|**IL Bytes Jitted / sec**|Displays the number of CIL bytes that are JIT-compiled per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Standard Jit Failures**|Displays the peak number of methods the JIT compiler has failed to compile since the application started. This failure can occur if the CIL cannot be verified or if there is an internal error in the JIT compiler.| +|**Total # of IL Bytes Jitted**|Displays the total CIL bytes JIT-compiled since the application started. This counter is equivalent to the **# of IL Bytes Jitted** counter.| ## Loading performance counters diff --git a/docs/framework/interop/default-marshalling-for-arrays.md b/docs/framework/interop/default-marshalling-for-arrays.md index 0676ca8919027..0fc689d444efc 100644 --- a/docs/framework/interop/default-marshalling-for-arrays.md +++ b/docs/framework/interop/default-marshalling-for-arrays.md @@ -2,368 +2,368 @@ title: "Default Marshalling for Arrays" description: Understand default marshalling for arrays. Review managed arrays, unmanaged arrays, passing array parameters to .NET code, and passing arrays to COM. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "interop marshalling, arrays" - "arrays, interop marshalling" ms.assetid: 8a3cca8b-dd94-4e3d-ad9a-9ee7590654bc --- # Default Marshalling for Arrays -In an application consisting entirely of managed code, the common language runtime passes array types as In/Out parameters. In contrast, the interop marshaller passes an array as In parameters by default. - - With [pinning optimization](copying-and-pinning.md), a blittable array can appear to operate as an In/Out parameter when interacting with objects in the same apartment. However, if you later export the code to a type library used to generate the cross-machine proxy, and that library is used to marshal your calls across apartments, the calls can revert to true In parameter behavior. - - Arrays are complex by nature, and the distinctions between managed and unmanaged arrays warrant more information than other non-blittable types. - -## Managed Arrays - - Managed array types can vary; however, the class is the base class of all array types. The **System.Array** class has properties for determining the rank, length, and lower and upper bounds of an array, as well as methods for accessing, sorting, searching, copying, and creating arrays. - - These array types are dynamic and do not have a corresponding static type defined in the base class library. It is convenient to think of each combination of element type and rank as a distinct type of array. Therefore, a one-dimensional array of integers is of a different type than a one-dimensional array of double types. Similarly a two-dimensional array of integers is different from a one-dimensional array of integers. The bounds of the array are not considered when comparing types. - - As the following table shows, any instance of a managed array must be of a specific element type, rank, and lower bound. - -|Managed array type|Element type|Rank|Lower bound|Signature notation| -|------------------------|------------------|----------|-----------------|------------------------| -|**ELEMENT_TYPE_ARRAY**|Specified by type.|Specified by rank.|Optionally specified by bounds.|*type* **[** *n*,*m* **]**| -|**ELEMENT_TYPE_CLASS**|Unknown|Unknown|Unknown|**System.Array**| -|**ELEMENT_TYPE_SZARRAY**|Specified by type.|1|0|*type* **[** *n* **]**| - -## Unmanaged Arrays - - Unmanaged arrays are either COM-style safe arrays or C-style arrays with fixed or variable length. Safe arrays are self-describing arrays that carry the type, rank, and bounds of the associated array data. C-style arrays are one-dimensional typed arrays with a fixed lower bound of 0. The marshalling service has limited support for both types of arrays. - -## Passing Array Parameters to .NET Code - - Both C-style arrays and safe arrays can be passed to .NET code from unmanaged code as either a safe array or a C-style array. The following table shows the unmanaged type value and the imported type. - -|Unmanaged type|Imported type| -|--------------------|-------------------| -|**SafeArray(** *Type* **)**|**ELEMENT_TYPE_SZARRAY** **\<** *ConvertedType* **>**

Rank = 1, lower bound = 0. Size is known only if provided in the managed signature. Safe arrays that are not rank = 1 or lower bound = 0 cannot be marshalled as **SZARRAY**.| -|*Type* **[]**|**ELEMENT_TYPE_SZARRAY** **\<** *ConvertedType* **>**

Rank = 1, lower bound = 0. Size is known only if provided in the managed signature.| - -### Safe Arrays - - When a safe array is imported from a type library to a .NET assembly, the array is converted to a one-dimensional array of a known type (such as **int**). The same type conversion rules that apply to parameters also apply to array elements. For example, a safe array of **BSTR** types becomes a managed array of strings and a safe array of variants becomes a managed array of objects. The **SAFEARRAY** element type is captured from the type library and saved in the **SAFEARRAY** value of the enumeration. - - Because the rank and bounds of the safe array cannot be determined from the type library, the rank is assumed to equal 1 and the lower bound is assumed to equal 0. The rank and bounds must be defined in the managed signature produced by the [Type Library Importer (Tlbimp.exe)](../tools/tlbimp-exe-type-library-importer.md). If the rank passed to the method at run time differs, a is thrown. If the type of the array passed at run time differs, a is thrown. The following example shows safe arrays in managed and unmanaged code. - - **Unmanaged signature** - +In an application consisting entirely of managed code, the common language runtime passes array types as In/Out parameters. In contrast, the interop marshaller passes an array as In parameters by default. + + With [pinning optimization](copying-and-pinning.md), a blittable array can appear to operate as an In/Out parameter when interacting with objects in the same apartment. However, if you later export the code to a type library used to generate the cross-machine proxy, and that library is used to marshal your calls across apartments, the calls can revert to true In parameter behavior. + + Arrays are complex by nature, and the distinctions between managed and unmanaged arrays warrant more information than other non-blittable types. + +## Managed Arrays + + Managed array types can vary; however, the class is the base class of all array types. The **System.Array** class has properties for determining the rank, length, and lower and upper bounds of an array, as well as methods for accessing, sorting, searching, copying, and creating arrays. + + These array types are dynamic and do not have a corresponding static type defined in the base class library. It is convenient to think of each combination of element type and rank as a distinct type of array. Therefore, a one-dimensional array of integers is of a different type than a one-dimensional array of double types. Similarly a two-dimensional array of integers is different from a one-dimensional array of integers. The bounds of the array are not considered when comparing types. + + As the following table shows, any instance of a managed array must be of a specific element type, rank, and lower bound. + +|Managed array type|Element type|Rank|Lower bound|Signature notation| +|------------------------|------------------|----------|-----------------|------------------------| +|**ELEMENT_TYPE_ARRAY**|Specified by type.|Specified by rank.|Optionally specified by bounds.|*type* **[** *n*,*m* **]**| +|**ELEMENT_TYPE_CLASS**|Unknown|Unknown|Unknown|**System.Array**| +|**ELEMENT_TYPE_SZARRAY**|Specified by type.|1|0|*type* **[** *n* **]**| + +## Unmanaged Arrays + + Unmanaged arrays are either COM-style safe arrays or C-style arrays with fixed or variable length. Safe arrays are self-describing arrays that carry the type, rank, and bounds of the associated array data. C-style arrays are one-dimensional typed arrays with a fixed lower bound of 0. The marshalling service has limited support for both types of arrays. + +## Passing Array Parameters to .NET Code + + Both C-style arrays and safe arrays can be passed to .NET code from unmanaged code as either a safe array or a C-style array. The following table shows the unmanaged type value and the imported type. + +|Unmanaged type|Imported type| +|--------------------|-------------------| +|**SafeArray(** *Type* **)**|**ELEMENT_TYPE_SZARRAY** **\<** *ConvertedType* **>**

Rank = 1, lower bound = 0. Size is known only if provided in the managed signature. Safe arrays that are not rank = 1 or lower bound = 0 cannot be marshalled as **SZARRAY**.| +|*Type* **[]**|**ELEMENT_TYPE_SZARRAY** **\<** *ConvertedType* **>**

Rank = 1, lower bound = 0. Size is known only if provided in the managed signature.| + +### Safe Arrays + + When a safe array is imported from a type library to a .NET assembly, the array is converted to a one-dimensional array of a known type (such as **int**). The same type conversion rules that apply to parameters also apply to array elements. For example, a safe array of **BSTR** types becomes a managed array of strings and a safe array of variants becomes a managed array of objects. The **SAFEARRAY** element type is captured from the type library and saved in the **SAFEARRAY** value of the enumeration. + + Because the rank and bounds of the safe array cannot be determined from the type library, the rank is assumed to equal 1 and the lower bound is assumed to equal 0. The rank and bounds must be defined in the managed signature produced by the [Type Library Importer (Tlbimp.exe)](../tools/tlbimp-exe-type-library-importer.md). If the rank passed to the method at run time differs, a is thrown. If the type of the array passed at run time differs, a is thrown. The following example shows safe arrays in managed and unmanaged code. + + **Unmanaged signature** + ```cpp -HRESULT New1([in] SAFEARRAY( int ) ar); -HRESULT New2([in] SAFEARRAY( DATE ) ar); -HRESULT New3([in, out] SAFEARRAY( BSTR ) *ar); -``` - - **Managed signature** - -```vb -Sub New1( _ - ar() As Integer) +HRESULT New1([in] SAFEARRAY( int ) ar); +HRESULT New2([in] SAFEARRAY( DATE ) ar); +HRESULT New3([in, out] SAFEARRAY( BSTR ) *ar); +``` + + **Managed signature** + +```vb +Sub New1( _ + ar() As Integer) Sub New2( _ - ar() As DateTime) + ar() As DateTime) Sub New3(ByRef _ - ar() As String) -``` - -```csharp -void New1([MarshalAs(UnmanagedType.SafeArray, SafeArraySubType=VT_I4)] int[] ar) ; + ar() As String) +``` + +```csharp +void New1([MarshalAs(UnmanagedType.SafeArray, SafeArraySubType=VT_I4)] int[] ar) ; void New2([MarshalAs(UnmanagedType.SafeArray, SafeArraySubType=VT_DATE)] - DateTime[] ar); + DateTime[] ar); void New3([MarshalAs(UnmanagedType.SafeArray, SafeArraySubType=VT_BSTR)] - ref String[] ar); -``` - - Multidimensional, or nonzero-bound safe arrays, can be marshalled into managed code if the method signature produced by Tlbimp.exe is modified to indicate an element type of **ELEMENT_TYPE_ARRAY** instead of **ELEMENT_TYPE_SZARRAY**. Alternatively, you can use the **/sysarray** switch with Tlbimp.exe to import all arrays as objects. In cases where the array being passed is known to be multidimensional, you can edit the Microsoft intermediate language (MSIL) code produced by Tlbimp.exe and then recompile it. For details about how to modify MSIL code, see [Customizing Runtime Callable Wrappers](/previous-versions/dotnet/netframework-4.0/e753eftz(v=vs.100)). - -### C-Style Arrays - - When a C-style array is imported from a type library to a .NET assembly, the array is converted to **ELEMENT_TYPE_SZARRAY**. - - The array element type is determined from the type library and preserved during the import. The same conversion rules that apply to parameters also apply to array elements. For example, an array of **LPStr** types becomes an array of **String** types. Tlbimp.exe captures the array element type and applies the attribute to the parameter. - - The array rank is assumed to equal 1. If the rank is greater than 1, the array is marshalled as a one-dimensional array in column-major order. The lower bound always equals 0. - - Type libraries can contain arrays of fixed or variable length. Tlbimp.exe can import only fixed-length arrays from type libraries because type libraries lack the information needed to marshal variable-length arrays. With fixed-length arrays, the size is imported from the type library and captured in the **MarshalAsAttribute** that is applied to the parameter. - - You must manually define type libraries containing variable-length arrays, as shown in the following example. - - **Unmanaged signature** - + ref String[] ar); +``` + + Multidimensional, or nonzero-bound safe arrays, can be marshalled into managed code if the method signature produced by Tlbimp.exe is modified to indicate an element type of **ELEMENT_TYPE_ARRAY** instead of **ELEMENT_TYPE_SZARRAY**. Alternatively, you can use the **/sysarray** switch with Tlbimp.exe to import all arrays as objects. In cases where the array being passed is known to be multidimensional, you can edit the common intermediate language (CIL) code produced by Tlbimp.exe and then recompile it. For details about how to modify CIL code, see [Customizing Runtime Callable Wrappers](/previous-versions/dotnet/netframework-4.0/e753eftz(v=vs.100)). + +### C-Style Arrays + + When a C-style array is imported from a type library to a .NET assembly, the array is converted to **ELEMENT_TYPE_SZARRAY**. + + The array element type is determined from the type library and preserved during the import. The same conversion rules that apply to parameters also apply to array elements. For example, an array of **LPStr** types becomes an array of **String** types. Tlbimp.exe captures the array element type and applies the attribute to the parameter. + + The array rank is assumed to equal 1. If the rank is greater than 1, the array is marshalled as a one-dimensional array in column-major order. The lower bound always equals 0. + + Type libraries can contain arrays of fixed or variable length. Tlbimp.exe can import only fixed-length arrays from type libraries because type libraries lack the information needed to marshal variable-length arrays. With fixed-length arrays, the size is imported from the type library and captured in the **MarshalAsAttribute** that is applied to the parameter. + + You must manually define type libraries containing variable-length arrays, as shown in the following example. + + **Unmanaged signature** + ```cpp -HRESULT New1(int ar[10]); -HRESULT New2(double ar[10][20]); -HRESULT New3(LPWStr ar[10]); -``` - - **Managed signature** - -```vb -Sub New1( _ - ar() As Integer) -Sub New2( _ - ar() As Double) -Sub New2( _ - ar() As String) -``` - -```csharp -void New1([MarshalAs(UnmanagedType.LPArray, SizeConst=10)] int[] ar); -void New2([MarshalAs(UnmanagedType.LPArray, SizeConst=200)] double[] ar); +HRESULT New1(int ar[10]); +HRESULT New2(double ar[10][20]); +HRESULT New3(LPWStr ar[10]); +``` + + **Managed signature** + +```vb +Sub New1( _ + ar() As Integer) +Sub New2( _ + ar() As Double) +Sub New2( _ + ar() As String) +``` + +```csharp +void New1([MarshalAs(UnmanagedType.LPArray, SizeConst=10)] int[] ar); +void New2([MarshalAs(UnmanagedType.LPArray, SizeConst=200)] double[] ar); void New2([MarshalAs(UnmanagedType.LPArray, - ArraySubType=UnmanagedType.LPWStr, SizeConst=10)] String[] ar); -``` - - Although you can apply the **size_is** or **length_is** attributes to an array in Interface Definition Language (IDL) source to convey the size to a client, the Microsoft Interface Definition Language (MIDL) compiler does not propagate that information to the type library. Without knowing the size, the interop marshalling service cannot marshal the array elements. Consequently, variable-length arrays are imported as reference arguments. For example: - - **Unmanaged signature** - + ArraySubType=UnmanagedType.LPWStr, SizeConst=10)] String[] ar); +``` + + Although you can apply the **size_is** or **length_is** attributes to an array in Interface Definition Language (IDL) source to convey the size to a client, the Microsoft Interface Definition Language (MIDL) compiler does not propagate that information to the type library. Without knowing the size, the interop marshalling service cannot marshal the array elements. Consequently, variable-length arrays are imported as reference arguments. For example: + + **Unmanaged signature** + ```cpp -HRESULT New1(int ar[]); -HRESULT New2(int ArSize, [size_is(ArSize)] double ar[]); -HRESULT New3(int ElemCnt, [length_is(ElemCnt)] LPStr ar[]); -``` - - **Managed signature** - -```vb -Sub New1(ByRef ar As Integer) -Sub New2(ByRef ar As Double) -Sub New3(ByRef ar As String) -``` - -```csharp +HRESULT New1(int ar[]); +HRESULT New2(int ArSize, [size_is(ArSize)] double ar[]); +HRESULT New3(int ElemCnt, [length_is(ElemCnt)] LPStr ar[]); +``` + + **Managed signature** + +```vb +Sub New1(ByRef ar As Integer) +Sub New2(ByRef ar As Double) +Sub New3(ByRef ar As String) +``` + +```csharp void New1(ref int ar); void New2(ref double ar); void New3(ref String ar); -``` - - You can provide the marshaller with the array size by editing the Microsoft intermediate language (MSIL) code produced by Tlbimp.exe and then recompiling it. For details about how to modify MSIL code, see [Customizing Runtime Callable Wrappers](/previous-versions/dotnet/netframework-4.0/e753eftz(v=vs.100)). To indicate the number of elements in the array, apply the type to the array parameter of the managed method definition in one of the following ways: - +``` + + You can provide the marshaller with the array size by editing the common intermediate language (CIL) code produced by Tlbimp.exe and then recompiling it. For details about how to modify CIL code, see [Customizing Runtime Callable Wrappers](/previous-versions/dotnet/netframework-4.0/e753eftz(v=vs.100)). To indicate the number of elements in the array, apply the type to the array parameter of the managed method definition in one of the following ways: + - Identify another parameter that contains the number of elements in the array. The parameters are identified by position, starting with the first parameter as number 0. - - ```vb - Sub [New](ElemCnt As Integer, _ - \ _ - ar() As Integer) - ``` - - ```csharp - void New( + + ```vb + Sub [New](ElemCnt As Integer, _ + \ _ + ar() As Integer) + ``` + + ```csharp + void New( int ElemCnt, - [MarshalAs(UnmanagedType.LPArray, SizeParamIndex=0)] int[] ar ); - ``` - -- Define the size of the array as a constant. For example: - - ```vb - Sub [New](\ _ - ar() As Integer) - ``` - - ```csharp - void New( - [MarshalAs(UnmanagedType.LPArray, SizeConst=128)] int[] ar ); - ``` - - When marshalling arrays from unmanaged code to managed code, the marshaller checks the **MarshalAsAttribute** associated with the parameter to determine the array size. If the array size is not specified, only one element is marshalled. - + [MarshalAs(UnmanagedType.LPArray, SizeParamIndex=0)] int[] ar ); + ``` + +- Define the size of the array as a constant. For example: + + ```vb + Sub [New](\ _ + ar() As Integer) + ``` + + ```csharp + void New( + [MarshalAs(UnmanagedType.LPArray, SizeConst=128)] int[] ar ); + ``` + + When marshalling arrays from unmanaged code to managed code, the marshaller checks the **MarshalAsAttribute** associated with the parameter to determine the array size. If the array size is not specified, only one element is marshalled. + > [!NOTE] -> The **MarshalAsAttribute** has no effect on marshalling managed arrays to unmanaged code. In that direction, the array size is determined by examination. There is no way to marshal a subset of a managed array. - - The interop marshaller uses the **CoTaskMemAlloc** and **CoTaskMemFree** methods on Windows or **malloc** and **free** methods on other operating systems to allocate and retrieve memory. Memory allocation performed by unmanaged code must also use these methods. - -## Passing Arrays to COM - - All managed array types can be passed to unmanaged code from managed code. Depending on the managed type and the attributes applied to it, the array can be accessed as a safe array or a C-style array, as shown in the following table. - -|Managed array type|Exported as| -|------------------------|-----------------| -|**ELEMENT_TYPE_SZARRAY** **\<** *type* **>**| **.SafeArray(** *type* **)**

**UnmanagedType.LPArray**

Type is provided in the signature. Rank is always 1, lower bound is always 0. Size is always known at run time.| -|**ELEMENT_TYPE_ARRAY** **\<** *type* **>** **\<** *rank* **>**[**\<** *bounds* **>**]|**UnmanagedType.SafeArray(** *type* **)**

**UnmanagedType.LPArray**

Type, rank, bounds are provided in the signature. Size is always known at run time.| -|**ELEMENT_TYPE_CLASS** **\<****>**|**UT_Interface**

**UnmanagedType.SafeArray(** *type* **)**

Type, rank, bounds, and size are always known at run time.| - - There is a limitation in OLE Automation relating to arrays of structures that contain LPSTR or LPWSTR. Therefore, **String** fields have to be marshalled as **UnmanagedType.BSTR**. Otherwise, an exception will be thrown. - -### ELEMENT_TYPE_SZARRAY - - When a method containing an **ELEMENT_TYPE_SZARRAY** parameter (one-dimensional array) is exported from a .NET assembly to a type library, the array parameter is converted to a **SAFEARRAY** of a given type. The same conversion rules apply to the array element types. The contents of the managed array are automatically copied from managed memory into the **SAFEARRAY**. For example: - -#### Managed signature - -```vb -Sub [New](ar() As Long) -Sub [New](ar() As String) -``` - -```csharp -void New(long[] ar ); -void New(String[] ar ); -``` - -#### Unmanaged signature - +> The **MarshalAsAttribute** has no effect on marshalling managed arrays to unmanaged code. In that direction, the array size is determined by examination. There is no way to marshal a subset of a managed array. + + The interop marshaller uses the **CoTaskMemAlloc** and **CoTaskMemFree** methods on Windows or **malloc** and **free** methods on other operating systems to allocate and retrieve memory. Memory allocation performed by unmanaged code must also use these methods. + +## Passing Arrays to COM + + All managed array types can be passed to unmanaged code from managed code. Depending on the managed type and the attributes applied to it, the array can be accessed as a safe array or a C-style array, as shown in the following table. + +|Managed array type|Exported as| +|------------------------|-----------------| +|**ELEMENT_TYPE_SZARRAY** **\<** *type* **>**| **.SafeArray(** *type* **)**

**UnmanagedType.LPArray**

Type is provided in the signature. Rank is always 1, lower bound is always 0. Size is always known at run time.| +|**ELEMENT_TYPE_ARRAY** **\<** *type* **>** **\<** *rank* **>**[**\<** *bounds* **>**]|**UnmanagedType.SafeArray(** *type* **)**

**UnmanagedType.LPArray**

Type, rank, bounds are provided in the signature. Size is always known at run time.| +|**ELEMENT_TYPE_CLASS** **\<****>**|**UT_Interface**

**UnmanagedType.SafeArray(** *type* **)**

Type, rank, bounds, and size are always known at run time.| + + There is a limitation in OLE Automation relating to arrays of structures that contain LPSTR or LPWSTR. Therefore, **String** fields have to be marshalled as **UnmanagedType.BSTR**. Otherwise, an exception will be thrown. + +### ELEMENT_TYPE_SZARRAY + + When a method containing an **ELEMENT_TYPE_SZARRAY** parameter (one-dimensional array) is exported from a .NET assembly to a type library, the array parameter is converted to a **SAFEARRAY** of a given type. The same conversion rules apply to the array element types. The contents of the managed array are automatically copied from managed memory into the **SAFEARRAY**. For example: + +#### Managed signature + +```vb +Sub [New](ar() As Long) +Sub [New](ar() As String) +``` + +```csharp +void New(long[] ar ); +void New(String[] ar ); +``` + +#### Unmanaged signature + ```cpp HRESULT New([in] SAFEARRAY( long ) ar); -HRESULT New([in] SAFEARRAY( BSTR ) ar); -``` - - The rank of the safe arrays is always 1 and the lower bound is always 0. The size is determined at run time by the size of the managed array being passed. - - The array can also be marshalled as a C-style array by using the attribute. For example: - -#### Managed signature - -```vb -Sub [New]( _ - ar() As Long, size as Integer) -Sub [New]( _ - ar() As String, size as Integer) -Sub [New]( _ - ar() As String, size as Integer) -``` - -```csharp +HRESULT New([in] SAFEARRAY( BSTR ) ar); +``` + + The rank of the safe arrays is always 1 and the lower bound is always 0. The size is determined at run time by the size of the managed array being passed. + + The array can also be marshalled as a C-style array by using the attribute. For example: + +#### Managed signature + +```vb +Sub [New]( _ + ar() As Long, size as Integer) +Sub [New]( _ + ar() As String, size as Integer) +Sub [New]( _ + ar() As String, size as Integer) +``` + +```csharp void New([MarshalAs(UnmanagedType.LPArray, SizeParamIndex=1)] - long [] ar, int size ); + long [] ar, int size ); void New([MarshalAs(UnmanagedType.LPArray, SizeParamIndex=1)] - String [] ar, int size ); + String [] ar, int size ); void New([MarshalAs(UnmanagedType.LPArray, ArraySubType= UnmanagedType.LPStr, SizeParamIndex=1)] - String [] ar, int size ); -``` - -#### Unmanaged signature - + String [] ar, int size ); +``` + +#### Unmanaged signature + ```cpp HRESULT New(long ar[]); HRESULT New(BSTR ar[]); -HRESULT New(LPStr ar[]); -``` - - Although the marshaller has the length information needed to marshal the array, the array length is usually passed as a separate argument to convey the length to the callee. - -### ELEMENT_TYPE_ARRAY - - When a method containing an **ELEMENT_TYPE_ARRAY** parameter is exported from a .NET assembly to a type library, the array parameter is converted to a **SAFEARRAY** of a given type. The contents of the managed array are automatically copied from managed memory into the **SAFEARRAY**. For example: - -#### Managed signature - -```vb -Sub [New](ar(,) As Long) -Sub [New](ar(,) As String) -``` - -```csharp -void New( long [,] ar ); -void New( String [,] ar ); -``` - -#### Unmanaged signature - +HRESULT New(LPStr ar[]); +``` + + Although the marshaller has the length information needed to marshal the array, the array length is usually passed as a separate argument to convey the length to the callee. + +### ELEMENT_TYPE_ARRAY + + When a method containing an **ELEMENT_TYPE_ARRAY** parameter is exported from a .NET assembly to a type library, the array parameter is converted to a **SAFEARRAY** of a given type. The contents of the managed array are automatically copied from managed memory into the **SAFEARRAY**. For example: + +#### Managed signature + +```vb +Sub [New](ar(,) As Long) +Sub [New](ar(,) As String) +``` + +```csharp +void New( long [,] ar ); +void New( String [,] ar ); +``` + +#### Unmanaged signature + ```cpp HRESULT New([in] SAFEARRAY( long ) ar); -HRESULT New([in] SAFEARRAY( BSTR ) ar); -``` - - The rank, size, and bounds of the safe arrays are determined at run time by the characteristics of the managed array. - - The array can also be marshalled as a C-style array by applying the attribute. For example: - -#### Managed signature - -```vb -Sub [New]( _ - ar(,) As Long, size As Integer) -Sub [New]( _ - ar(,) As String, size As Integer) -``` - -```csharp +HRESULT New([in] SAFEARRAY( BSTR ) ar); +``` + + The rank, size, and bounds of the safe arrays are determined at run time by the characteristics of the managed array. + + The array can also be marshalled as a C-style array by applying the attribute. For example: + +#### Managed signature + +```vb +Sub [New]( _ + ar(,) As Long, size As Integer) +Sub [New]( _ + ar(,) As String, size As Integer) +``` + +```csharp void New([MarshalAs(UnmanagedType.LPARRAY, SizeParamIndex=1)] - long [,] ar, int size ); + long [,] ar, int size ); void New([MarshalAs(UnmanagedType.LPARRAY, ArraySubType= UnmanagedType.LPStr, SizeParamIndex=1)] - String [,] ar, int size ); -``` - -#### Unmanaged signature - + String [,] ar, int size ); +``` + +#### Unmanaged signature + ```cpp HRESULT New(long ar[]); -HRESULT New(LPStr ar[]); -``` - - Nested arrays cannot be marshalled. For example, the following signature generates an error when exported with the [Type Library Exporter (Tlbexp.exe)](../tools/tlbexp-exe-type-library-exporter.md). - -#### Managed signature - -```vb -Sub [New](ar()()() As Long) -``` - -```csharp -void New(long [][][] ar ); -``` - -### ELEMENT_TYPE_CLASS \ - - When a method containing a parameter is exported from a .NET assembly to a type library, the array parameter is converted to an **_Array** interface. The contents of the managed array are accessible only through the methods and properties of the **_Array** interface. **System.Array** can also be marshalled as a **SAFEARRAY** by using the attribute. When marshalled as a safe array, the array elements are marshalled as variants. For example: - -#### Managed signature - -```vb -Sub New1( ar As System.Array ) -Sub New2( ar As System.Array ) -``` - -```csharp -void New1( System.Array ar ); -void New2( [MarshalAs(UnmanagedType.Safe array)] System.Array ar ); -``` - -#### Unmanaged signature - +HRESULT New(LPStr ar[]); +``` + + Nested arrays cannot be marshalled. For example, the following signature generates an error when exported with the [Type Library Exporter (Tlbexp.exe)](../tools/tlbexp-exe-type-library-exporter.md). + +#### Managed signature + +```vb +Sub [New](ar()()() As Long) +``` + +```csharp +void New(long [][][] ar ); +``` + +### ELEMENT_TYPE_CLASS \ + + When a method containing a parameter is exported from a .NET assembly to a type library, the array parameter is converted to an **_Array** interface. The contents of the managed array are accessible only through the methods and properties of the **_Array** interface. **System.Array** can also be marshalled as a **SAFEARRAY** by using the attribute. When marshalled as a safe array, the array elements are marshalled as variants. For example: + +#### Managed signature + +```vb +Sub New1( ar As System.Array ) +Sub New2( ar As System.Array ) +``` + +```csharp +void New1( System.Array ar ); +void New2( [MarshalAs(UnmanagedType.Safe array)] System.Array ar ); +``` + +#### Unmanaged signature + ```cpp HRESULT New([in] _Array *ar); -HRESULT New([in] SAFEARRAY(VARIANT) ar); -``` - -### Arrays within Structures - - Unmanaged structures can contain embedded arrays. By default, these embedded array fields are marshalled as a SAFEARRAY. In the following example, `s1` is an embedded array that is allocated directly within the structure itself. - -#### Unmanaged representation - +HRESULT New([in] SAFEARRAY(VARIANT) ar); +``` + +### Arrays within Structures + + Unmanaged structures can contain embedded arrays. By default, these embedded array fields are marshalled as a SAFEARRAY. In the following example, `s1` is an embedded array that is allocated directly within the structure itself. + +#### Unmanaged representation + ```cpp -struct MyStruct { - short s1[128]; -} -``` - - Arrays can be marshalled as , which requires you to set the field. The size can be set only as a constant. The following code shows the corresponding managed definition of `MyStruct`. - -```vb -Public Structure MyStruct - Public _ - s1() As Short -End Structure -``` - -```csharp -[StructLayout(LayoutKind.Sequential)] -public struct MyStruct { - [MarshalAs(UnmanagedType.ByValArray, SizeConst=128)] public short[] s1; -} -``` - +struct MyStruct { + short s1[128]; +} +``` + + Arrays can be marshalled as , which requires you to set the field. The size can be set only as a constant. The following code shows the corresponding managed definition of `MyStruct`. + +```vb +Public Structure MyStruct + Public _ + s1() As Short +End Structure +``` + +```csharp +[StructLayout(LayoutKind.Sequential)] +public struct MyStruct { + [MarshalAs(UnmanagedType.ByValArray, SizeConst=128)] public short[] s1; +} +``` + ## See also - [Default Marshalling Behavior](default-marshalling-behavior.md) diff --git a/docs/framework/performance/clr-etw-events.md b/docs/framework/performance/clr-etw-events.md index 6f23c14b3b2fd..5e0510340a804 100644 --- a/docs/framework/performance/clr-etw-events.md +++ b/docs/framework/performance/clr-etw-events.md @@ -2,7 +2,7 @@ title: "CLR ETW Events" description: "See articles about common language runtime (CLR) event tracing for Windows (ETW) events. There are two event providers: runtime provider and rundown provider." ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "CLR ETW events" - "ETW, common language runtime" - "ETW, CLR events" @@ -10,52 +10,52 @@ ms.assetid: ef2b31c3-7426-43e7-9924-92339b96556d --- # CLR ETW Events -The topics in this section describe event tracing for Windows (ETW) events. Each event has an associated keyword and level, which are described in the [CLR ETW Keywords and Levels](clr-etw-keywords-and-levels.md) topic. The CLR has two providers for the events: - -- The runtime provider, which raises events depending on which keywords (categories of events) are enabled. The CLR runtime provider GUID is e13c0d23-ccbc-4e12-931b-d9cc2eee27e4. - -- The rundown provider, which has special-purpose uses. The CLR rundown provider GUID is a669021c-c450-4609-a035-5af59af4df18. - - For more information about the providers, see [CLR ETW Providers](clr-etw-providers.md). - -## In This Section - - [Runtime Information Events](runtime-information-etw-events.md) - Captures information about the runtime, including the SKU, version number, the manner in which the runtime was activated, the command-line parameters it was started with, the GUID (if applicable), and other relevant information. - - [Exception Thrown_V1 Event](exception-thrown-v1-etw-event.md) - Captures information about exceptions that are thrown. - - [Contention Events](contention-etw-events.md) - Captures information about contention for monitor locks or native locks that the runtime uses. - - [Thread Pool Events](thread-pool-etw-events.md) - Captures information about worker thread pools and I/O thread pools. - - [Loader Events](loader-etw-events.md) - Captures information about loading and unloading application domains, assemblies, and modules. - - [Method Events](method-etw-events.md) - Captures information about CLR methods for symbol resolution. - - [Garbage Collection Events](garbage-collection-etw-events.md) - Captures information pertaining to garbage collection, to help in diagnostics and debugging. - - [JIT Tracing Events](jit-tracing-etw-events.md) - Captures information about just-in-time (JIT) inlining and tail calls. - - [Interop Events](interop-etw-events.md) - Captures information about Microsoft intermediate language (MSIL) stub generation and caching. - - [ARM Events](application-domain-resource-monitoring-arm-etw-events.md) - Captures detailed diagnostic information about the state of an application domain. - - [Security Events](security-etw-events.md) - Captures information about strong name and Authenticode verification. - - [Stack Event](stack-etw-event.md) - Captures information that is used with other events to generate stack traces after an event is raised. - +The topics in this section describe event tracing for Windows (ETW) events. Each event has an associated keyword and level, which are described in the [CLR ETW Keywords and Levels](clr-etw-keywords-and-levels.md) topic. The CLR has two providers for the events: + +- The runtime provider, which raises events depending on which keywords (categories of events) are enabled. The CLR runtime provider GUID is e13c0d23-ccbc-4e12-931b-d9cc2eee27e4. + +- The rundown provider, which has special-purpose uses. The CLR rundown provider GUID is a669021c-c450-4609-a035-5af59af4df18. + + For more information about the providers, see [CLR ETW Providers](clr-etw-providers.md). + +## In This Section + + [Runtime Information Events](runtime-information-etw-events.md) + Captures information about the runtime, including the SKU, version number, the manner in which the runtime was activated, the command-line parameters it was started with, the GUID (if applicable), and other relevant information. + + [Exception Thrown_V1 Event](exception-thrown-v1-etw-event.md) + Captures information about exceptions that are thrown. + + [Contention Events](contention-etw-events.md) + Captures information about contention for monitor locks or native locks that the runtime uses. + + [Thread Pool Events](thread-pool-etw-events.md) + Captures information about worker thread pools and I/O thread pools. + + [Loader Events](loader-etw-events.md) + Captures information about loading and unloading application domains, assemblies, and modules. + + [Method Events](method-etw-events.md) + Captures information about CLR methods for symbol resolution. + + [Garbage Collection Events](garbage-collection-etw-events.md) + Captures information pertaining to garbage collection, to help in diagnostics and debugging. + + [JIT Tracing Events](jit-tracing-etw-events.md) + Captures information about just-in-time (JIT) inlining and tail calls. + + [Interop Events](interop-etw-events.md) + Captures information about common intermediate language (CIL) stub generation and caching. + + [ARM Events](application-domain-resource-monitoring-arm-etw-events.md) + Captures detailed diagnostic information about the state of an application domain. + + [Security Events](security-etw-events.md) + Captures information about strong name and Authenticode verification. + + [Stack Event](stack-etw-event.md) + Captures information that is used with other events to generate stack traces after an event is raised. + ## See also - [Improve Debugging And Performance Tuning With ETW](/archive/msdn-magazine/2007/april/event-tracing-improve-debugging-and-performance-tuning-with-etw) diff --git a/docs/framework/performance/interop-etw-events.md b/docs/framework/performance/interop-etw-events.md index a30aef0363f06..28b727c7136ea 100644 --- a/docs/framework/performance/interop-etw-events.md +++ b/docs/framework/performance/interop-etw-events.md @@ -1,6 +1,6 @@ --- title: "Interop ETW Events" -description: Review interop ETW (event tracing for Windows) events, which capture information about Microsoft intermediate language (MSIL) stub generation & caching in .NET. +description: Review interop ETW (event tracing for Windows) events, which capture information about common intermediate language (CIL) stub generation & caching in .NET. ms.date: "03/30/2017" helpviewer_keywords: - "interop events [.NET Framework]" @@ -8,7 +8,7 @@ helpviewer_keywords: --- # Interop ETW Events -Interop events capture information about Microsoft intermediate language (MSIL) stub generation and caching. +Interop events capture information about common intermediate language (CIL) stub generation and caching. ## ILStubGenerated Event @@ -22,7 +22,7 @@ The following table shows the keyword and level. (For more information, see [CLR |Event|Event ID|Raised when| |-----------|--------------|-----------------| -|`ILStubGenerated`|88|The MSIL stub has been generated.| +|`ILStubGenerated`|88|The CIL stub has been generated.| The following table shows the event data. @@ -37,7 +37,7 @@ The following table shows the keyword and level. (For more information, see [CLR |ManagedInteropMethodSignature|win:UnicodeString|The signature of the managed interop method.| |NativeMethodSignature|win:UnicodeString|The native method signature.| |StubMethodSignature|win:UnicodeString|The stub method signature.| -|StubMethodILCode|win:UnicodeString|The MSIL code for the stub method.| +|StubMethodILCode|win:UnicodeString|The CIL code for the stub method.| |ClrInstanceID|win:UInt16|Unique ID for the instance of CLR or CoreCLR.| ## ILStubCacheHit Event @@ -52,7 +52,7 @@ The following table shows the keyword and level. |Event|Event ID|Raised when| |-----------|--------------|-----------------| -|`ILStubCacheHit`|89|The MSIL cache has been accessed.| +|`ILStubCacheHit`|89|The CIL cache has been accessed.| The following table shows the event data. diff --git a/docs/framework/performance/loader-etw-events.md b/docs/framework/performance/loader-etw-events.md index 171bd9b3073f9..ba77e6af81b8b 100644 --- a/docs/framework/performance/loader-etw-events.md +++ b/docs/framework/performance/loader-etw-events.md @@ -98,7 +98,7 @@ These events collect information relating to loading and unloading application d |AssemblyID|win:UInt64|ID of the assembly in which this module resides.| |ModuleFlags|win:UInt32|0x1: Domain neutral module.

0x2: Module has a native image.

0x4: Dynamic module.

0x8: Manifest module.| |Reserved1|win:UInt32|Reserved field.| -|ModuleILPath|win:UnicodeString|Path of the Microsoft intermediate language (MSIL) image for the module, or dynamic module name if it is a dynamic assembly (null-terminated).| +|ModuleILPath|win:UnicodeString|Path of the common intermediate language (CIL) image for the module, or dynamic module name if it is a dynamic assembly (null-terminated).| |ModuleNativePath|win:UnicodeString|Path of the module native image, if present (null-terminated).| |ClrInstanceID|win:UInt16|Unique ID for the instance of CLR or CoreCLR.| |ManagedPdbSignature|win:GUID|GUID signature of the managed program database (PDB) that matches this module. (See Remarks.)| @@ -112,7 +112,7 @@ These events collect information relating to loading and unloading application d - The fields that have "Pdb" in their names can be used by profiling tools to locate PDBs that match the modules that were loaded during the profiling session. The values of these fields correspond to the data written into the IMAGE_DIRECTORY_ENTRY_DEBUG sections of the module normally used by debuggers to help locate PDBs that match the loaded modules. -- The field names that begin with "ManagedPdb" refer to the managed PDB corresponding to the MSIL module that was generated by the managed compiler (such as the C# or Visual Basic compiler). This PDB uses the managed PDB format, and describes how elements from the original managed source code, such as files, line numbers, and symbol names, map to MSIL elements that are compiled into the MSIL module. +- The field names that begin with "ManagedPdb" refer to the managed PDB corresponding to the CIL module that was generated by the managed compiler (such as the C# or Visual Basic compiler). This PDB uses the managed PDB format, and describes how elements from the original managed source code, such as files, line numbers, and symbol names, map to CIL elements that are compiled into the CIL module. - The field names that begin with "NativePdb" refer to the NGen PDB generated by calling `NGEN createPDB`. This PDB uses the native PDB format, and describes how elements from the original managed source code, such as files, line numbers, and symbol names, map to native elements that are compiled into the NGen module. @@ -143,7 +143,7 @@ These events collect information relating to loading and unloading application d |AppDomainID|win:UInt64|ID of the application domain in which this module is used.| |ModuleFlags|win:UInt32|0x1: Domain neutral module.

0x2: Module has a native image.

0x4: Dynamic module.

0x8: Manifest module.| |Reserved1|win:UInt32|Reserved field.| -|ModuleILPath|win:UnicodeString|Path of the MSIL image for the module, or dynamic module name if it is a dynamic assembly (null-terminated).| +|ModuleILPath|win:UnicodeString|Path of the CIL image for the module, or dynamic module name if it is a dynamic assembly (null-terminated).| |ModuleNativePath|win:UnicodeString|Path of the module native image, if present (null-terminated).| |ClrInstanceID|win:UInt16|Unique ID for the instance of CLR or CoreCLR.| diff --git a/docs/framework/performance/method-etw-events.md b/docs/framework/performance/method-etw-events.md index 1204bf711c223..81a8300d4dd4f 100644 --- a/docs/framework/performance/method-etw-events.md +++ b/docs/framework/performance/method-etw-events.md @@ -133,7 +133,7 @@ The following table shows the event data: |MethodID|win:UInt64|Unique identifier of the method.| |ModuleID|win:UInt64|Identifier of the module to which this method belongs.| |MethodToken|win:UInt32|0 for dynamic methods and JIT helpers.| -|MethodILSize|win:UInt32|The size of the Microsoft intermediate language (MSIL) for the method that is being JIT-compiled.| +|MethodILSize|win:UInt32|The size of the common intermediate language (CIL) for the method that is being JIT-compiled.| |MethodNameSpace|win:UnicodeString|Full class name associated with the method.| |MethodName|win:UnicodeString|Name of the method.| |MethodSignature|win:UnicodeString|Signature of the method (comma-separated list of type names).| diff --git a/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md b/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md index 9e7b4a13e724d..71e9563509755 100644 --- a/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md +++ b/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md @@ -15,7 +15,7 @@ ms.assetid: 0f8bf8fa-b993-478f-87ab-1a1a7976d298 --- # Security Issues in Reflection Emit -.NET Framework provides three ways to emit Microsoft intermediate language (MSIL), each with its own security issues: +.NET Framework provides three ways to emit common intermediate language (CIL), each with its own security issues: - [Dynamic Assemblies](#dynamic-assemblies) - [Anonymously Hosted Dynamic Methods](#anonymously-hosted-dynamic-methods) @@ -59,7 +59,7 @@ ms.assetid: 0f8bf8fa-b993-478f-87ab-1a1a7976d298 Instead, when an anonymously hosted dynamic method is created, the call stack is captured. When the method is constructed, security demands are made against the captured call stack. > [!NOTE] -> Conceptually, demands are made during the construction of the method. That is, demands could be made as each MSIL instruction is emitted. In the current implementation, all demands are made when the method is called or when the just-in-time (JIT) compiler is invoked, if the method is invoked without calling . +> Conceptually, demands are made during the construction of the method. That is, demands could be made as each CIL instruction is emitted. In the current implementation, all demands are made when the method is called or when the just-in-time (JIT) compiler is invoked, if the method is invoked without calling . If the application domain permits it, anonymously hosted dynamic methods can skip JIT visibility checks, subject to the following restriction: The nonpublic types and members accessed by an anonymously hosted dynamic method must be in assemblies whose grant sets are equal to, or subsets of, the grant set of the emitting call stack. This restricted ability to skip JIT visibility checks is enabled if the application domain grants with the flag. diff --git a/docs/framework/tools/al-exe-assembly-linker.md b/docs/framework/tools/al-exe-assembly-linker.md index 70f1f6095ac8b..e22289e17d474 100644 --- a/docs/framework/tools/al-exe-assembly-linker.md +++ b/docs/framework/tools/al-exe-assembly-linker.md @@ -43,30 +43,30 @@ You can specify the following `options`; you must specify **/out**. |**/algid:** `id`|Specifies an algorithm to hash all files in a multifile assembly except the file that contains the assembly manifest. The default algorithm is CALG_SHA1. See ALG_ID in the Platform SDK documentation for other algorithms. For the first release of the .NET Framework, only CALG_SHA1 and CALG_MD5 are valid.

The hash values are stored in the file table of the assembly manifest. At installation and load time, the assembly's files are checked against their hashes.

You can also specify this option as a custom attribute () in the source code for any module.| |**/base[address]:** `addr`|Specifies the address at which a DLL will be loaded on the user's computer at run time. Applications load faster if you specify the base address of the DLLs, instead of letting the operating system relocate the DLLs in the process space.| |**/bugreport**: `filename`|Creates a file (`filename`) that contains information for reporting bugs.| -|**/comp[any]:** `text`|Specifies a string for the Company field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, `text` appears in File Explorer as the `Company` property for the file. If you specify **/win32res**, the company information in the specified resource file appears as the `Company` property in File Explorer.

If text is an empty string (""), the Win32 `Company` resource appears as a single space.

If you specify **/win32res**, **/company** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|**/config[uration]:** `text`|Specifies a string for the Configuration field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If text is an empty string, the Win32 Configuration resource appears as a single space.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|**/copy[right]:** `text`|Specifies a string for the Copyright field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/copyright** appears in File Explorer as the Win32 Copyright resource.

If text is an empty string, the Win32 Copyright resource appears as a single space.

If you specify **/win32res**, **/copyright** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|**/c[ulture]:** `text`|Specifies the culture string to associate with the assembly. Valid values for cultures are those defined by the Internet Requests for Comments (RFC) document 1766 titled "Tags for the Identification of Languages."

Place the string in double quotation marks (" ") if `text` contains a space. There is no default culture string. This string is available for viewing with reflection.

For information about valid `text` strings, see the .

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|`/delay[sign][+ or -]`|Specifies whether the assembly will be fully or partially signed. Use **/delaysign-** if you want a fully signed assembly. Use **/delaysign+** if you only want to include the public key in the assembly.

When you request a fully signed assembly, *Al.exe* hashes the file that contains the manifest (assembly metadata) and signs that hash with the private key. The resulting digital signature is stored in the file that contains the manifest. When an assembly is delay signed, *Al.exe* does not compute and store the signature, but just reserves space in the file so the signature can be added later.

The default is **/delaysign-**.

The **/delaysign** option has no effect unless used with **/keyfile** or **/keyname**.

For example, using **/delaysign+** enables a tester to put the assembly in the global cache. After testing, you can fully sign the assembly by including the private key in the assembly.

Note: Before using the [*Gacutil.exe* (Global Assembly Cache Tool)](gacutil-exe-gac-tool.md) to put a delay-signed assembly into the global cache, use the [*Sn.exe* (Strong Name Tool)](sn-exe-strong-name-tool.md) to register the assembly for verification skipping. For example, `Sn.exe –Vr delaySignedAssembly`. Use this only for development.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|**/descr[iption]:** `text`|Specifies a string for the field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/description** appears in File Explorer as the Win32 **Comments** resource.

If text is an empty string, the Win32 **Comments** resource appears as a single space.

If you specify **/win32res**, **/description** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| +|**/comp[any]:** `text`|Specifies a string for the Company field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, `text` appears in File Explorer as the `Company` property for the file. If you specify **/win32res**, the company information in the specified resource file appears as the `Company` property in File Explorer.

If text is an empty string (""), the Win32 `Company` resource appears as a single space.

If you specify **/win32res**, **/company** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|**/config[uration]:** `text`|Specifies a string for the Configuration field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If text is an empty string, the Win32 Configuration resource appears as a single space.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|**/copy[right]:** `text`|Specifies a string for the Copyright field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/copyright** appears in File Explorer as the Win32 Copyright resource.

If text is an empty string, the Win32 Copyright resource appears as a single space.

If you specify **/win32res**, **/copyright** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|**/c[ulture]:** `text`|Specifies the culture string to associate with the assembly. Valid values for cultures are those defined by the Internet Requests for Comments (RFC) document 1766 titled "Tags for the Identification of Languages."

Place the string in double quotation marks (" ") if `text` contains a space. There is no default culture string. This string is available for viewing with reflection.

For information about valid `text` strings, see the .

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|`/delay[sign][+ or -]`|Specifies whether the assembly will be fully or partially signed. Use **/delaysign-** if you want a fully signed assembly. Use **/delaysign+** if you only want to include the public key in the assembly.

When you request a fully signed assembly, *Al.exe* hashes the file that contains the manifest (assembly metadata) and signs that hash with the private key. The resulting digital signature is stored in the file that contains the manifest. When an assembly is delay signed, *Al.exe* does not compute and store the signature, but just reserves space in the file so the signature can be added later.

The default is **/delaysign-**.

The **/delaysign** option has no effect unless used with **/keyfile** or **/keyname**.

For example, using **/delaysign+** enables a tester to put the assembly in the global cache. After testing, you can fully sign the assembly by including the private key in the assembly.

Note: Before using the [*Gacutil.exe* (Global Assembly Cache Tool)](gacutil-exe-gac-tool.md) to put a delay-signed assembly into the global cache, use the [*Sn.exe* (Strong Name Tool)](sn-exe-strong-name-tool.md) to register the assembly for verification skipping. For example, `Sn.exe –Vr delaySignedAssembly`. Use this only for development.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|**/descr[iption]:** `text`|Specifies a string for the field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/description** appears in File Explorer as the Win32 **Comments** resource.

If text is an empty string, the Win32 **Comments** resource appears as a single space.

If you specify **/win32res**, **/description** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| |**/e[vidence]:** `file`|Embeds `file` in the assembly with the resource name of Security.Evidence.

You cannot use Security.Evidence for regular resources.| -|**/fileversion:** `version`|Specifies a string for the **File Version** field in the assembly. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/fileversion** will be used as the Win32 **File Version** resource. If you do not specify **/fileversion**, the Win32 **File Version** resource will be populated by the Win32 **Assembly Version** resource.

If **/win32res** is specified, **/fileversion** does not affect the Win32 resource.

You can also specify this option as a custom attribute (AssemblyFileVersionAttribute) in the source code for any MSIL module.| -|**/flags:** `flags`|Specifies a value for the `Flags` field in the assembly. Possible values for `flags`:

0x0000
The assembly is side-by-side compatible.

0x0010
The assembly cannot execute with other versions if they are executing in the same application domain.

0x0020
The assembly cannot execute with other versions if they are executing in the same process.

0x0030
The assembly cannot execute with other versions if they are executing on the same computer.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| +|**/fileversion:** `version`|Specifies a string for the **File Version** field in the assembly. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/fileversion** will be used as the Win32 **File Version** resource. If you do not specify **/fileversion**, the Win32 **File Version** resource will be populated by the Win32 **Assembly Version** resource.

If **/win32res** is specified, **/fileversion** does not affect the Win32 resource.

You can also specify this option as a custom attribute (AssemblyFileVersionAttribute) in the source code for any CIL module.| +|**/flags:** `flags`|Specifies a value for the `Flags` field in the assembly. Possible values for `flags`:

0x0000
The assembly is side-by-side compatible.

0x0010
The assembly cannot execute with other versions if they are executing in the same application domain.

0x0020
The assembly cannot execute with other versions if they are executing in the same process.

0x0030
The assembly cannot execute with other versions if they are executing on the same computer.

You can also specify this option as a custom attribute () in the source code for any CIL module.| |**/fullpaths**|Causes *Al.exe* to use the absolute path for any files that are reported in an error message.| |**/help**|Displays command syntax and options for the tool.| -|**/keyf[ile]:** `filename`|Specifies a file (`filename`) that contains a key pair or just a public key to sign an assembly. The compiler inserts the public key in the assembly manifest and then signs the final assembly with the private key. See the [Strong Name Tool (*Sn.exe*)](sn-exe-strong-name-tool.md) for information about generating key files and installing key pairs into key containers.

If you are using delayed signing, this file will usually have the public key but not the private key.

The public key (of the key pair) information appears in the .publickey field of the assembly.

You can also specify this option as a custom attribute () in the source code for any MSIL module.

If both **/keyfile** and **/keyname** are specified (either by command-line option or by custom attribute) in the same compilation, *Al.exe* will first try the container specified with **/keyname**. If that succeeds, the assembly is signed with the information in the key container. If *Al.exe* does not find the key container, it will try the file specified with **/keyfile**. If that succeeds, the assembly is signed with the information in the key file and the key information will be installed in the key container (similar to the -i option in [*Sn.exe*](sn-exe-strong-name-tool.md)) so that on the next compilation, the **/keyname** option will be valid.| -|**/keyn[ame]:** `text`|Specifies a container that holds a key pair. This will sign the assembly (give it a strong name) by inserting a public key into the assembly manifest. *Al.exe* will then sign the final assembly with the private key.

Use *Sn.exe* to generate a key pair.

The key information appears in the .publickey field of the assembly.

Place `text` in double quotation marks (" ") if there is an embedded space.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| +|**/keyf[ile]:** `filename`|Specifies a file (`filename`) that contains a key pair or just a public key to sign an assembly. The compiler inserts the public key in the assembly manifest and then signs the final assembly with the private key. See the [Strong Name Tool (*Sn.exe*)](sn-exe-strong-name-tool.md) for information about generating key files and installing key pairs into key containers.

If you are using delayed signing, this file will usually have the public key but not the private key.

The public key (of the key pair) information appears in the .publickey field of the assembly.

You can also specify this option as a custom attribute () in the source code for any CIL module.

If both **/keyfile** and **/keyname** are specified (either by command-line option or by custom attribute) in the same compilation, *Al.exe* will first try the container specified with **/keyname**. If that succeeds, the assembly is signed with the information in the key container. If *Al.exe* does not find the key container, it will try the file specified with **/keyfile**. If that succeeds, the assembly is signed with the information in the key file and the key information will be installed in the key container (similar to the -i option in [*Sn.exe*](sn-exe-strong-name-tool.md)) so that on the next compilation, the **/keyname** option will be valid.| +|**/keyn[ame]:** `text`|Specifies a container that holds a key pair. This will sign the assembly (give it a strong name) by inserting a public key into the assembly manifest. *Al.exe* will then sign the final assembly with the private key.

Use *Sn.exe* to generate a key pair.

The key information appears in the .publickey field of the assembly.

Place `text` in double quotation marks (" ") if there is an embedded space.

You can also specify this option as a custom attribute () in the source code for any CIL module.| |**/main:** `method`|Specifies the fully qualified name (`class`.`method`) of the method to use as an entry point when converting a module to an executable file.| |**/nologo**|Suppresses the banner, or logo, displayed at the command line when you invoke *Al.exe*.| |**/out:** `filename`|Specifies the name of the file produced by *Al.exe*. This is a required option.| |**/platform:** `text`|Limits which platform this code can run on; must be one of x86, Itanium, x64, anycpu (the default), or anycpu32bitpreferred.| -|**/prod[uct]:** `text`|Specifies a string for the **Product** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/product** appears in File Explorer as the Win32 **Product Name** resource.

If text is an empty string, the Win32 **Product Name** resource appears as a single space.

If you specify **/win32res**, **/product** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|**/productv[ersion]:** `text`|Specifies a string for the **Product Version** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/productversion** will be used as the Win32 **Product Version** resource. If you do not specify **/productversion**, the Win32 **Product Version** resource will be populated by the Win32 **File Version** resource.

If you specify **/win32res**, **/productversion** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| +|**/prod[uct]:** `text`|Specifies a string for the **Product** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/product** appears in File Explorer as the Win32 **Product Name** resource.

If text is an empty string, the Win32 **Product Name** resource appears as a single space.

If you specify **/win32res**, **/product** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|**/productv[ersion]:** `text`|Specifies a string for the **Product Version** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/productversion** will be used as the Win32 **Product Version** resource. If you do not specify **/productversion**, the Win32 **Product Version** resource will be populated by the Win32 **File Version** resource.

If you specify **/win32res**, **/productversion** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| |**/t[arget]:** `lib[rary]` | `exe` | `win[exe]`|Specifies the file format of the output file: `lib[rary]` (code library), `exe` (console application), or `win[exe]` (Windows-based application). The default is `lib[rary]`.| |**/template:** `filename`|Specifies the assembly, `filename`, from which to inherit all assembly metadata, except the culture field.

An assembly that you create with **/template** will be a satellite assembly.| -|**/title:** `text`|Specifies a string for the **Title** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/title** appears in File Explorer as the Win32 **Description** resource, which is used by the shell as the friendly name of an application. It is also displayed on the **Open With** submenu of the shortcut menu for a file type for which there are multiple supporting applications.

If text is an empty string, the Win32 **Description** resource appears as a single space.

If you specify **/win32res**, **/title** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|**/trade[mark]:** `text`|Specifies a string for the **Trademark** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/trademark** appears in File Explorer as the Win32 **Trademark** resource.

If text is an empty string, the Win32 **Trademark** resource appears as a single space.

If you specify **/win32res**, **/trademark** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|**/v[ersion]:** `version`|Specifies version information for this assembly. The format of the version string is `major`.`minor`.`build`.`revision`. The default value is 0.

If you do specify **/version**, you must specify `major`. If you specify `major` and `minor`, you can specify an asterisk (\*)for `build`. This causes `build` to be equal to the number of days since January 1, 2000, local time, and `revision` to be equal to the number of seconds since midnight of the current day, local time, divided by 2.

If you specify `major`, `minor`, and `build`, you can specify an asterisk for `revision`. This causes `revision` to be equal to the number of seconds since midnight of the current day, local time, divided by 2.

To summarize, the valid version strings are as follows:

X

X.X

X.X.\*

X.X.X

X.X.X.\*

X.X.X.X

where X is any unsigned short constant except 65535 (0-65534).

If you do not specify **/win32res**, **/version** will be used as the Win32 **Assembly Version** resource.

If you do not specify **/win32res**, **/productversion**, and **/fileversion**, **/version** will be used for the **Assembly Version**, File Version, and **Product Version** Win32 resources.

If you specify **/win32res**, **/version** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| +|**/title:** `text`|Specifies a string for the **Title** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/title** appears in File Explorer as the Win32 **Description** resource, which is used by the shell as the friendly name of an application. It is also displayed on the **Open With** submenu of the shortcut menu for a file type for which there are multiple supporting applications.

If text is an empty string, the Win32 **Description** resource appears as a single space.

If you specify **/win32res**, **/title** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|**/trade[mark]:** `text`|Specifies a string for the **Trademark** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/trademark** appears in File Explorer as the Win32 **Trademark** resource.

If text is an empty string, the Win32 **Trademark** resource appears as a single space.

If you specify **/win32res**, **/trademark** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|**/v[ersion]:** `version`|Specifies version information for this assembly. The format of the version string is `major`.`minor`.`build`.`revision`. The default value is 0.

If you do specify **/version**, you must specify `major`. If you specify `major` and `minor`, you can specify an asterisk (\*)for `build`. This causes `build` to be equal to the number of days since January 1, 2000, local time, and `revision` to be equal to the number of seconds since midnight of the current day, local time, divided by 2.

If you specify `major`, `minor`, and `build`, you can specify an asterisk for `revision`. This causes `revision` to be equal to the number of seconds since midnight of the current day, local time, divided by 2.

To summarize, the valid version strings are as follows:

X

X.X

X.X.\*

X.X.X

X.X.X.\*

X.X.X.X

where X is any unsigned short constant except 65535 (0-65534).

If you do not specify **/win32res**, **/version** will be used as the Win32 **Assembly Version** resource.

If you do not specify **/win32res**, **/productversion**, and **/fileversion**, **/version** will be used for the **Assembly Version**, File Version, and **Product Version** Win32 resources.

If you specify **/win32res**, **/version** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| |**/win32icon:** `filename`|Inserts an .ico file in the assembly. The .ico file gives the output file the desired appearance in File Explorer.| |**/win32res:** `filename`|Inserts a Win32 resource (.res file) in the output file. A Win32 resource file can be created by using the Resource Compiler. The Resource Compiler is invoked when you compile a Visual C++ program; a .res file is created from the .rc file.| |`@filename`|Specifies a response file that contains *Al.exe* commands.

Commands in the response file can appear one per line or on the same line, separated by one or more spaces.| diff --git a/docs/framework/tools/index.md b/docs/framework/tools/index.md index 093ddfc14f847..f4cc2f8bdb8ab 100644 --- a/docs/framework/tools/index.md +++ b/docs/framework/tools/index.md @@ -82,7 +82,7 @@ Enables you to tune native image assemblies using common end-user scenarios. Mpg Improves the performance of managed applications through the use of native images (files containing compiled processor-specific machine code). The runtime can use native images from the cache instead of using the just-in-time (JIT) compiler to compile the original assembly. [Peverify.exe (PEVerify Tool)](peverify-exe-peverify-tool.md)\ -Helps you verify whether your Microsoft intermediate language (MSIL) code and associated metadata meet type safety requirements. +Helps you verify whether your common intermediate language (CIL) code and associated metadata meet type safety requirements. [Regasm.exe (Assembly Registration Tool)](regasm-exe-assembly-registration-tool.md)\ Reads the metadata within an assembly and adds the necessary entries to the registry. This enables COM clients to appear as .NET Framework classes. diff --git a/docs/framework/tools/installutil-exe-installer-tool.md b/docs/framework/tools/installutil-exe-installer-tool.md index 653749a7bac54..16dde69b7bc21 100644 --- a/docs/framework/tools/installutil-exe-installer-tool.md +++ b/docs/framework/tools/installutil-exe-installer-tool.md @@ -83,7 +83,7 @@ Installutil.exe uses reflection to inspect the specified assemblies and to find Installutil.exe cannot install or uninstall delay-signed assemblies, but it can install or uninstall strong-named assemblies. -Starting with .NET Framework version 2.0, the 32-bit version of the common language runtime (CLR) ships with only the 32-bit version of the Installer tool, but the 64-bit version of the CLR ships with both 32-bit and 64-bit versions of the Installer tool. When using the 64-bit CLR, use the 32-bit Installer tool to install 32-bit assemblies, and the 64-bit Installer tool to install 64-bit and Microsoft intermediate language (MSIL) assemblies. Both versions of the Installer tool behave the same. +Starting with .NET Framework version 2.0, the 32-bit version of the common language runtime (CLR) ships with only the 32-bit version of the Installer tool, but the 64-bit version of the CLR ships with both 32-bit and 64-bit versions of the Installer tool. When using the 64-bit CLR, use the 32-bit Installer tool to install 32-bit assemblies, and the 64-bit Installer tool to install 64-bit and common intermediate language (CIL) assemblies. Both versions of the Installer tool behave the same. You cannot use Installutil.exe to deploy a Windows service that was created by using C++, because Installutil.exe cannot recognize the embedded native code that is produced by the C++ compiler. If you try to deploy a C++ Windows service with Installutil.exe, an exception such as will be thrown. To work with this scenario, move the service code to a C++ module, and then write the installer object in C# or Visual Basic. diff --git a/docs/framework/tools/mdbg-exe.md b/docs/framework/tools/mdbg-exe.md index 6a24725965235..05bd997528bc5 100644 --- a/docs/framework/tools/mdbg-exe.md +++ b/docs/framework/tools/mdbg-exe.md @@ -2,104 +2,104 @@ title: "MDbg.exe (.NET Framework Command-Line Debugger)" description: Understand MDbg.exe, the command-line debugger for .NET, which helps tools vendors and application developers find and fix bugs in programs targeting the CLR. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "command-line debugger [.NET Framework]" - "MDbg.exe" ms.assetid: 28a3f509-07e2-4dbe-81df-874c5e969cc4 --- # MDbg.exe (.NET Framework Command-Line Debugger) -The NET Framework Command-Line Debugger helps tools vendors and application developers find and fix bugs in programs that target the .NET Framework common language runtime. This tool uses the runtime debugging API to provide debugging services. You can use MDbg.exe to debug only managed code; there is no support for debugging unmanaged code. - +The NET Framework Command-Line Debugger helps tools vendors and application developers find and fix bugs in programs that target the .NET Framework common language runtime. This tool uses the runtime debugging API to provide debugging services. You can use MDbg.exe to debug only managed code; there is no support for debugging unmanaged code. + This tool is available through NuGet. For installation information, see [MDbg 0.1.0](https://www.nuget.org/packages/MDbg/0.1.0). To run the tool, use the Package Manager Console. For more information about how to use the Package Manager Console, see the [Package Manager Console](/nuget/tools/package-manager-console) article. - -At the Package Manager prompt, type the following: - -## Syntax - -```console -MDbg [ProgramName[arguments]] [options] -``` - -## Commands - - When you are in the debugger (as indicated by the **mdbg>** prompt), type one of the commands described in the next section: - - **command** [*arguments*] - - MDbg.exe commands are case-sensitive. - -|Command|Description| -|-------------|-----------------| -|**ap**[**rocess**] [*number*]|Switches to another debugged process or prints available processes. The numbers are not real process IDs (PIDs), but a 0-indexed list.| -|**a**[**ttach**] [*pid*]|Attaches to a process or prints available processes.| -|**b**[**reak**] [*ClassName.Method* | *FileName:LineNo*]|Sets a breakpoint at the specified method. Modules are scanned sequentially.

- **break** *FileName:LineNo* sets a breakpoint at a location in the source.
- **break** *~number* sets a breakpoint on a symbol recently displayed with the **x** command.
- **break** *module!ClassName.Method+IlOffset* sets a breakpoint on the fully qualified location.| -|**block**[**ingObjects**]|Displays monitor locks, which are blocking threads.| -|**ca**[**tch**] [*exceptionType*]|Causes the debugger to break on all exceptions, and not just on the unhandled exceptions.| -|**cl**[**earException**]|Marks the current exception as handled so that execution can continue. If the cause of the exception has not been dealt with, the exception may be quickly rethrown.| -|**conf**[**ig**] [*option value*]|Displays all configurable options and shows how the options are invoked without any optional values. If the option is specified, sets `value` as the current option. The following options are currently available:

- `extpath` sets the path to search for extensions when the `load` command is used.
- `extpath+` adds a path for loading extensions.| -|**del**[**ete**]|Deletes a breakpoint.| -|**de**[**tach**]|Detaches from a debugged process.| -|**d**[**own**] [*frames*]|Moves the active stack frame down.| -|**echo**|Echoes a message to the console.| -|**enableNotif**[**ication**] *typeName* 0|1|Enables (1) or disables (0) custom notifications for the specified type.| -|**ex**[**it**] [*exitcode*]|Exits the MDbg.exe shell, and optionally specifies the process exit code.| -|**fo**[**reach**] [*OtherCommand*]|Performs a command on all threads. *OtherCommand* is a valid command that operates on one thread; **foreach** *OtherCommand* performs the same command on all threads.| -|**f**[**unceval**] [`-ad` *Num*] *functionName* [*args ...* ]|Performs a function evaluation on the current active thread where the function to evaluate is *functionName*. The function name must be fully qualified, including namespaces.

The `-ad` option specifies the application domain to use to resolve the function. If the `-ad` option is not specified, the application domain for resolution defaults to the application domain where the thread that is used for function evaluation is located.

If the function that is being evaluated is not static, the first parameter passed in should be a `this` pointer. All application domains are searched for arguments to the function evaluation..

To request a value from an application domain, prefix the variable with the module and application domain name; for example, `funceval -ad 0 System.Object.ToString hello.exe#0!MyClass.g_rootRef`. This command evaluates the function `System.Object.ToString` in the application domain `0`. Because the `ToString` method is an instance function, the first parameter must be a `this` pointer.| -|**g**[**o**]|Causes the program to continue until it encounters a breakpoint, the program exits, or an event (for example, an unhandled exception) causes the program to stop.| -|**h**[**elp**] [*command*]

-or-

**?** [*command*]|Displays a description of all commands or a detailed description of a specified command.| -|**ig**[**nore**] [*event*]|Causes the debugger to stop on unhandled exceptions only.| -|**int**[**ercept**] *FrameNumber*|Rolls the debugger back to a specified frame number.

If the debugger encounters an exception, use this command to roll the debugger back to the specified frame number. You can change the program state by using the **set** command and continue by using the **go** command.| -|**k**[**ill**]|Stops the active process.| -|**l**[**ist**] [*modules* | *appdomains* | *assemblies*]|Displays the loaded modules, application domains, or assemblies.| -|**lo**[**ad**] *assemblyName*|Loads an extension in the following manner: The specified assembly is loaded and an attempt is then made to run the static method `LoadExtension` from the `Microsoft.Tools.Mdbg.Extension.Extension` type.| -|**log** [*eventType*]|Set or display the events to be logged.| -|**mo**[**de**] [*option on/off*]|Sets different debugger options. Use `mode` with no options to get a list of the debugging modes and their current settings.| -|**mon**[**itorInfo**] *monitorReference*|Displays object monitor lock information.| -|**newo**[**bj**] *typeName* [*arguments...*]|Creates a new object of type *typeName*.| -|**n**[**ext**]|Runs code and moves to the next line (even if the next line includes many function calls).| -|**Opendump** *pathToDumpFile*|Opens the specified dump file for debugging.| -|**o**[**ut**]|Moves to the end of the current function.| -|**pa**[**th**] [*pathName*]|Searches the specified path for the source files if the location in the binaries is not available.| -|**p**[**rint**] [*var*] | [`-d`]|Prints all variables in scope (**print**), prints the specified variable (**print** *var*), or prints the debugger variables (**print**`-d`).| -|**printe**[**xception**] [*-r*]|Prints the last exception on the current thread. Use the `–r` (recursive) option to traverse the `InnerException` property on the exception object to get information about the entire chain of exceptions.| -|**pro**[**cessenum**]|Displays the active processes.| -|**q**[**uit**] [*exitcode*]|Quits the MDbg.exe shell, optionally specifying the process exit code.| -|**re**[**sume**] [`*` | [`~`]*threadNumber*]|Resumes the current thread or the thread specified by the *threadNumber* parameter.

If the *threadNumber* parameter is specified as `*` or if the thread number starts with `~`, the command applies to all threads except the one specified by *threadNumber*.

Resuming a non-suspended thread has no effect.| -|**r**[**un**] [`-d`(`ebug`) | -`o`(`ptimize`) |`-enc`] [[*path_to_exe*] [*args_to_exe*]]|Stops the current process (if there is one) and starts a new one. If no executable argument is passed, this command runs the program that was previously executed with the `run` command. If the executable argument is provided, the specified program is run using the optionally supplied arguments.

If class load, module load, and thread start events are ignored (as they are by default), the program stops on the first executable instruction of the main thread.

You can force the debugger to just-in-time (JIT) compile the code by using one of the following three flags:

- `-d` *(* `ebug` *)* disables optimizations. This is the default for MDbg.exe.
- `-o` *(* `ptimize` *)* forces the code to run more like it does outside the debugger, but also makes the debugging experience more difficult. This is the default for use outside the debugger.
- `-enc` enables the Edit and Continue feature but incurs a performance hit.| -|**Set** *variable*=*value*|Changes the value of any in-scope variable.

You can also create your own debugger variables and assign reference values to them from within your application. These values act as handles to the original value, and even the original value is out of scope. All debugger variables must begin with `$` (for example, `$var`). Clear these handles by setting them to nothing using the following command:

`set $var=`| -|**Setip** [`-il`] *number*|Sets the current instruction pointer (IP) in the file to the specified position. If you specify the `-il` option, the number represents a Microsoft intermediate language (MSIL) offset in the method. Otherwise, the number represents a source line number.| -|**sh**[**ow**] [*lines*]|Specifies the number of lines to show.| -|**s**[**tep**]|Moves execution into the next function on the current line, or moves to the next line if there is no function to step into.| -|**su**[**spend**] [\* | [~]*threadNumber*]|Suspends the current thread or the thread specified by the *threadNumber* parameter. If *threadNumber* is specified as `*`, the command applies to all threads. If the thread number starts with `~`, the command applies to all threads except the one specified by *threadNumber*. Suspended threads are excluded from running when the process is run by either the **go** or **step** command. If there are no non-suspended threads in the process and you issue the **go** command, the process will not continue. In that case, press CTRL-C to break into the process.| -|**sy**[**mbol**] *commandName* [*commandValue*]|Specifies one of the following commands:

- `symbol path` [`"value"`] - Displays or sets the current symbol path.
- `symbol addpath` `"value"` - Adds to your current symbol path.
- `symbol reload` [`"module"`] - Reloads either all symbols or the symbols for the specified module.
- `symbol list` [`module`] - Shows the currently loaded symbols for either all modules or the specified module.| -|**t**[**hread**] [*newThread*] [-*nick nickname*`]`|The thread command with no parameters displays all managed threads in the current process. Threads are usually identified by their thread numbers; however, if the thread has an assigned nickname, the nickname is displayed instead. You can use the `-nick` parameter to assign a nickname to a thread.

- **thread** `-nick` *threadName* assigns a nickname to the currently running thread.

Nicknames cannot be numbers. If the current thread already has an assigned nickname, the old nickname is replaced with the new one. If the new nickname is an empty string (""), the nickname for the current thread is deleted and no new nickname is assigned to the thread.| -|**u**[**p**]|Moves the active stack frame up.| -|**uwgc**[**handle**] [*var*] | [*address*]|Prints the variable tracked by a handle. The handle can be specified by name or address.| -|**when**|Displays the currently active `when` statements.

**when** **delete all** | `num` [`num` [`num` …]] - Deletes the `when` statement specified by the number, or all `when` statements if `all` is specified.

**when** `stopReason` [`specific_condition`] **do**`cmd` [`cmd` [`cmd` …] ] - The *stopReason* parameter can be one of the following:

`StepComplete`, `ProcessExited`, `ThreadCreated`, `BreakpointHit`, `ModuleLoaded`, `ClassLoaded`, `AssemblyLoaded`, `AssemblyUnloaded`, `ControlCTrapped`, `ExceptionThrown`, `UnhandledExceptionThrown`, `AsyncStop`, `AttachComplete`, `UserBreak`, `EvalComplete`, `EvalException`, `RemapOpportunityReached`, `NativeStop`.

*specific_condition* can be one of the following:

- *number* - For `ThreadCreated` and `BreakpointHit`, triggers action only when stopped by a thread ID/breakpoint number with same value.
- [`!`]*name* - For `ModuleLoaded`, `ClassLoaded`, `AssemblyLoaded`, `AssemblyUnloaded`, `ExceptionThrown`, and `UnhandledExceptionThrown`, triggers action only when the name matches the name of the *stopReason*.

*specific_condition* must be empty for other values of *stopReason*.| -|**w**[**here**] [`-v`] [`-c` *depth*] [*threadID*]|Displays debug information about stack frames.

- The `-v` option provides verbose information about each displayed stack frame.
- Specifying a number for `depth` limits how many frames are displayed. Use the **all** command to display all frames. The default is 100.
- If you specify the *threadID* parameter, you can control which thread is associated with the stack. The default is the current thread only. Use the **all** command to get all threads.| -|**x** [`-c`*numSymbols*] [*module*[`!`*pattern*]]|Displays functions that match the `pattern` for a module.

If *numSymbols* is specified, the output is limited to the specified number. If `!` (indicating a regular expression) is not specified for *pattern*, all functions are displayed. If *module* is not provided, all loaded modules are displayed. Symbols (*~#*) can be used to set breakpoints using the **break** command.| - -## Remarks - - Compile the application to be debugged by using compiler-specific flags that cause your compiler to generate debugging symbols. Refer to your compiler's documentation for more information about these flags. You can debug optimized applications, but some debugging information will be missing. For example, many local variables will not be visible and source lines will be inaccurate. - - After you compile your application, type **mdbg** at the command prompt to start a debugging session, as shown in the following example. - -```console -C:\Program Files\Microsoft Visual Studio 8\VC>mdbg -MDbg (Managed debugger) v2.0.50727.42 (RTM.050727-4200) started. -Copyright (C) Microsoft Corporation. All rights reserved. - -For information about commands type "help"; -to exit program type "quit". -mdbg> -``` - - The `mdbg>` prompt indicates that you are in the debugger. - - Once you are in the debugger, use the commands and arguments described in the previous section. - + +At the Package Manager prompt, type the following: + +## Syntax + +```console +MDbg [ProgramName[arguments]] [options] +``` + +## Commands + + When you are in the debugger (as indicated by the **mdbg>** prompt), type one of the commands described in the next section: + + **command** [*arguments*] + + MDbg.exe commands are case-sensitive. + +|Command|Description| +|-------------|-----------------| +|**ap**[**rocess**] [*number*]|Switches to another debugged process or prints available processes. The numbers are not real process IDs (PIDs), but a 0-indexed list.| +|**a**[**ttach**] [*pid*]|Attaches to a process or prints available processes.| +|**b**[**reak**] [*ClassName.Method* | *FileName:LineNo*]|Sets a breakpoint at the specified method. Modules are scanned sequentially.

- **break** *FileName:LineNo* sets a breakpoint at a location in the source.
- **break** *~number* sets a breakpoint on a symbol recently displayed with the **x** command.
- **break** *module!ClassName.Method+IlOffset* sets a breakpoint on the fully qualified location.| +|**block**[**ingObjects**]|Displays monitor locks, which are blocking threads.| +|**ca**[**tch**] [*exceptionType*]|Causes the debugger to break on all exceptions, and not just on the unhandled exceptions.| +|**cl**[**earException**]|Marks the current exception as handled so that execution can continue. If the cause of the exception has not been dealt with, the exception may be quickly rethrown.| +|**conf**[**ig**] [*option value*]|Displays all configurable options and shows how the options are invoked without any optional values. If the option is specified, sets `value` as the current option. The following options are currently available:

- `extpath` sets the path to search for extensions when the `load` command is used.
- `extpath+` adds a path for loading extensions.| +|**del**[**ete**]|Deletes a breakpoint.| +|**de**[**tach**]|Detaches from a debugged process.| +|**d**[**own**] [*frames*]|Moves the active stack frame down.| +|**echo**|Echoes a message to the console.| +|**enableNotif**[**ication**] *typeName* 0|1|Enables (1) or disables (0) custom notifications for the specified type.| +|**ex**[**it**] [*exitcode*]|Exits the MDbg.exe shell, and optionally specifies the process exit code.| +|**fo**[**reach**] [*OtherCommand*]|Performs a command on all threads. *OtherCommand* is a valid command that operates on one thread; **foreach** *OtherCommand* performs the same command on all threads.| +|**f**[**unceval**] [`-ad` *Num*] *functionName* [*args ...* ]|Performs a function evaluation on the current active thread where the function to evaluate is *functionName*. The function name must be fully qualified, including namespaces.

The `-ad` option specifies the application domain to use to resolve the function. If the `-ad` option is not specified, the application domain for resolution defaults to the application domain where the thread that is used for function evaluation is located.

If the function that is being evaluated is not static, the first parameter passed in should be a `this` pointer. All application domains are searched for arguments to the function evaluation..

To request a value from an application domain, prefix the variable with the module and application domain name; for example, `funceval -ad 0 System.Object.ToString hello.exe#0!MyClass.g_rootRef`. This command evaluates the function `System.Object.ToString` in the application domain `0`. Because the `ToString` method is an instance function, the first parameter must be a `this` pointer.| +|**g**[**o**]|Causes the program to continue until it encounters a breakpoint, the program exits, or an event (for example, an unhandled exception) causes the program to stop.| +|**h**[**elp**] [*command*]

-or-

**?** [*command*]|Displays a description of all commands or a detailed description of a specified command.| +|**ig**[**nore**] [*event*]|Causes the debugger to stop on unhandled exceptions only.| +|**int**[**ercept**] *FrameNumber*|Rolls the debugger back to a specified frame number.

If the debugger encounters an exception, use this command to roll the debugger back to the specified frame number. You can change the program state by using the **set** command and continue by using the **go** command.| +|**k**[**ill**]|Stops the active process.| +|**l**[**ist**] [*modules* | *appdomains* | *assemblies*]|Displays the loaded modules, application domains, or assemblies.| +|**lo**[**ad**] *assemblyName*|Loads an extension in the following manner: The specified assembly is loaded and an attempt is then made to run the static method `LoadExtension` from the `Microsoft.Tools.Mdbg.Extension.Extension` type.| +|**log** [*eventType*]|Set or display the events to be logged.| +|**mo**[**de**] [*option on/off*]|Sets different debugger options. Use `mode` with no options to get a list of the debugging modes and their current settings.| +|**mon**[**itorInfo**] *monitorReference*|Displays object monitor lock information.| +|**newo**[**bj**] *typeName* [*arguments...*]|Creates a new object of type *typeName*.| +|**n**[**ext**]|Runs code and moves to the next line (even if the next line includes many function calls).| +|**Opendump** *pathToDumpFile*|Opens the specified dump file for debugging.| +|**o**[**ut**]|Moves to the end of the current function.| +|**pa**[**th**] [*pathName*]|Searches the specified path for the source files if the location in the binaries is not available.| +|**p**[**rint**] [*var*] | [`-d`]|Prints all variables in scope (**print**), prints the specified variable (**print** *var*), or prints the debugger variables (**print**`-d`).| +|**printe**[**xception**] [*-r*]|Prints the last exception on the current thread. Use the `–r` (recursive) option to traverse the `InnerException` property on the exception object to get information about the entire chain of exceptions.| +|**pro**[**cessenum**]|Displays the active processes.| +|**q**[**uit**] [*exitcode*]|Quits the MDbg.exe shell, optionally specifying the process exit code.| +|**re**[**sume**] [`*` | [`~`]*threadNumber*]|Resumes the current thread or the thread specified by the *threadNumber* parameter.

If the *threadNumber* parameter is specified as `*` or if the thread number starts with `~`, the command applies to all threads except the one specified by *threadNumber*.

Resuming a non-suspended thread has no effect.| +|**r**[**un**] [`-d`(`ebug`) | -`o`(`ptimize`) |`-enc`] [[*path_to_exe*] [*args_to_exe*]]|Stops the current process (if there is one) and starts a new one. If no executable argument is passed, this command runs the program that was previously executed with the `run` command. If the executable argument is provided, the specified program is run using the optionally supplied arguments.

If class load, module load, and thread start events are ignored (as they are by default), the program stops on the first executable instruction of the main thread.

You can force the debugger to just-in-time (JIT) compile the code by using one of the following three flags:

- `-d` *(* `ebug` *)* disables optimizations. This is the default for MDbg.exe.
- `-o` *(* `ptimize` *)* forces the code to run more like it does outside the debugger, but also makes the debugging experience more difficult. This is the default for use outside the debugger.
- `-enc` enables the Edit and Continue feature but incurs a performance hit.| +|**Set** *variable*=*value*|Changes the value of any in-scope variable.

You can also create your own debugger variables and assign reference values to them from within your application. These values act as handles to the original value, and even the original value is out of scope. All debugger variables must begin with `$` (for example, `$var`). Clear these handles by setting them to nothing using the following command:

`set $var=`| +|**Setip** [`-il`] *number*|Sets the current instruction pointer (IP) in the file to the specified position. If you specify the `-il` option, the number represents a common intermediate language (CIL) offset in the method. Otherwise, the number represents a source line number.| +|**sh**[**ow**] [*lines*]|Specifies the number of lines to show.| +|**s**[**tep**]|Moves execution into the next function on the current line, or moves to the next line if there is no function to step into.| +|**su**[**spend**] [\* | [~]*threadNumber*]|Suspends the current thread or the thread specified by the *threadNumber* parameter. If *threadNumber* is specified as `*`, the command applies to all threads. If the thread number starts with `~`, the command applies to all threads except the one specified by *threadNumber*. Suspended threads are excluded from running when the process is run by either the **go** or **step** command. If there are no non-suspended threads in the process and you issue the **go** command, the process will not continue. In that case, press CTRL-C to break into the process.| +|**sy**[**mbol**] *commandName* [*commandValue*]|Specifies one of the following commands:

- `symbol path` [`"value"`] - Displays or sets the current symbol path.
- `symbol addpath` `"value"` - Adds to your current symbol path.
- `symbol reload` [`"module"`] - Reloads either all symbols or the symbols for the specified module.
- `symbol list` [`module`] - Shows the currently loaded symbols for either all modules or the specified module.| +|**t**[**hread**] [*newThread*] [-*nick nickname*`]`|The thread command with no parameters displays all managed threads in the current process. Threads are usually identified by their thread numbers; however, if the thread has an assigned nickname, the nickname is displayed instead. You can use the `-nick` parameter to assign a nickname to a thread.

- **thread** `-nick` *threadName* assigns a nickname to the currently running thread.

Nicknames cannot be numbers. If the current thread already has an assigned nickname, the old nickname is replaced with the new one. If the new nickname is an empty string (""), the nickname for the current thread is deleted and no new nickname is assigned to the thread.| +|**u**[**p**]|Moves the active stack frame up.| +|**uwgc**[**handle**] [*var*] | [*address*]|Prints the variable tracked by a handle. The handle can be specified by name or address.| +|**when**|Displays the currently active `when` statements.

**when** **delete all** | `num` [`num` [`num` …]] - Deletes the `when` statement specified by the number, or all `when` statements if `all` is specified.

**when** `stopReason` [`specific_condition`] **do**`cmd` [`cmd` [`cmd` …] ] - The *stopReason* parameter can be one of the following:

`StepComplete`, `ProcessExited`, `ThreadCreated`, `BreakpointHit`, `ModuleLoaded`, `ClassLoaded`, `AssemblyLoaded`, `AssemblyUnloaded`, `ControlCTrapped`, `ExceptionThrown`, `UnhandledExceptionThrown`, `AsyncStop`, `AttachComplete`, `UserBreak`, `EvalComplete`, `EvalException`, `RemapOpportunityReached`, `NativeStop`.

*specific_condition* can be one of the following:

- *number* - For `ThreadCreated` and `BreakpointHit`, triggers action only when stopped by a thread ID/breakpoint number with same value.
- [`!`]*name* - For `ModuleLoaded`, `ClassLoaded`, `AssemblyLoaded`, `AssemblyUnloaded`, `ExceptionThrown`, and `UnhandledExceptionThrown`, triggers action only when the name matches the name of the *stopReason*.

*specific_condition* must be empty for other values of *stopReason*.| +|**w**[**here**] [`-v`] [`-c` *depth*] [*threadID*]|Displays debug information about stack frames.

- The `-v` option provides verbose information about each displayed stack frame.
- Specifying a number for `depth` limits how many frames are displayed. Use the **all** command to display all frames. The default is 100.
- If you specify the *threadID* parameter, you can control which thread is associated with the stack. The default is the current thread only. Use the **all** command to get all threads.| +|**x** [`-c`*numSymbols*] [*module*[`!`*pattern*]]|Displays functions that match the `pattern` for a module.

If *numSymbols* is specified, the output is limited to the specified number. If `!` (indicating a regular expression) is not specified for *pattern*, all functions are displayed. If *module* is not provided, all loaded modules are displayed. Symbols (*~#*) can be used to set breakpoints using the **break** command.| + +## Remarks + + Compile the application to be debugged by using compiler-specific flags that cause your compiler to generate debugging symbols. Refer to your compiler's documentation for more information about these flags. You can debug optimized applications, but some debugging information will be missing. For example, many local variables will not be visible and source lines will be inaccurate. + + After you compile your application, type **mdbg** at the command prompt to start a debugging session, as shown in the following example. + +```console +C:\Program Files\Microsoft Visual Studio 8\VC>mdbg +MDbg (Managed debugger) v2.0.50727.42 (RTM.050727-4200) started. +Copyright (C) Microsoft Corporation. All rights reserved. + +For information about commands type "help"; +to exit program type "quit". +mdbg> +``` + + The `mdbg>` prompt indicates that you are in the debugger. + + Once you are in the debugger, use the commands and arguments described in the previous section. + ## See also - [Tools](index.md) diff --git a/docs/framework/tools/ngen-exe-native-image-generator.md b/docs/framework/tools/ngen-exe-native-image-generator.md index 047a2b4d49aee..8d09aff619f01 100644 --- a/docs/framework/tools/ngen-exe-native-image-generator.md +++ b/docs/framework/tools/ngen-exe-native-image-generator.md @@ -237,13 +237,13 @@ Hard binding can affect startup time, because all images that are hard bound to The following general considerations and application considerations may assist you in deciding whether to undertake the effort of evaluating native images for your application: -- Native images load faster than MSIL because they eliminate the need for many startup activities, such as JIT compilation and type-safety verification. +- Native images load faster than CIL because they eliminate the need for many startup activities, such as JIT compilation and type-safety verification. - Native images require a smaller initial working set because there is no need for the JIT compiler. - Native images enable code sharing between processes. -- Native images require more hard disk space than MSIL assemblies and may require considerable time to generate. +- Native images require more hard disk space than CIL assemblies and may require considerable time to generate. - Native images must be maintained. diff --git a/docs/framework/tools/peverify-exe-peverify-tool.md b/docs/framework/tools/peverify-exe-peverify-tool.md index 963bbde422e46..9ddbd3210af2f 100644 --- a/docs/framework/tools/peverify-exe-peverify-tool.md +++ b/docs/framework/tools/peverify-exe-peverify-tool.md @@ -1,8 +1,8 @@ --- title: "Peverify.exe (PEVerify Tool)" -description: Use Peverify.exe (portable executable verify) to help determine if Microsoft intermediate language (MSIL) code & metadata meet type safety standards in .NET. +description: Use Peverify.exe (portable executable verify) to help determine if MSIL code & metadata meet type safety standards in .NET. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "portable executable files, PEVerify" - "verifying MSIL and metadata" - "PEVerify tool" @@ -14,106 +14,106 @@ ms.assetid: f4f46f9e-8d08-4e66-a94b-0c69c9b0bbfa --- # Peverify.exe (PEVerify tool) -The PEVerify tool helps developers who generate Microsoft intermediate language (MSIL) (such as compiler writers and script engine developers) to determine whether their MSIL code and associated metadata meet type safety requirements. Some compilers generate verifiably type-safe code only if you avoid using certain language constructs. If you're using such a compiler, you may want to verify that you have not compromised the type safety of your code. You can run the PEVerify tool on your files to check the MSIL and metadata. - +The PEVerify tool helps developers who generate Microsoft intermediate language (MSIL) (such as compiler writers and script engine developers) to determine whether their MSIL code and associated metadata meet type safety requirements. Some compilers generate verifiably type-safe code only if you avoid using certain language constructs. If you're using such a compiler, you may want to verify that you have not compromised the type safety of your code. You can run the PEVerify tool on your files to check the MSIL and metadata. + This tool is automatically installed with Visual Studio. To run the tool, use [Visual Studio Developer Command Prompt or Visual Studio Developer PowerShell](/visualstudio/ide/reference/command-prompt-powershell). - -## Syntax - -```console -peverify filename [options] -``` - -## Parameters - -|Argument|Description| -|--------------|-----------------| -|*filename*|The portable executable (PE) file for which to check the MSIL and metadata.| - -|Option|Description| -|------------|-----------------| -|**/break=** *maxErrorCount*|Aborts verification after *maxErrorCount* errors.

This parameter is not supported in .NET Framework version 2.0 or later.| -|**/clock**|Measures and reports the following verification times in milliseconds:

**MD Val. cycle**
Metadata validation cycle

**MD Val. pure**
Metadata validation pure

**IL Ver. cycle**
Microsoft intermediate language (MSIL) verification cycle

**IL Ver pure**
MSIL verification pure

The **MD Val. cycle** and **IL Ver. cycle** times include the time required to perform necessary startup and shutdown procedures. The **MD Val. pure** and **IL Ver pure** times reflect the time required to perform the validation or verification only.| -|**/help**|Displays command syntax and options for the tool.| -|**/hresult**|Displays error codes in hexadecimal format.| -|**/ignore=** *hex.code* [, *hex.code*]|Ignores the specified error codes.| -|**/ignore=@** *responseFile*|Ignores the error codes listed in the specified response file.| -|**/il**|Performs MSIL type safety verification checks for methods implemented in the assembly specified by *filename*. The tool returns detailed descriptions for each problem found unless you specify the **/quiet** option.| -|**/md**|Performs metadata validation checks on the assembly specified by *filename*. This option walks the full metadata structure within the file and reports all validation problems encountered.| -|**/nologo**|Suppresses the display of product version and copyright information.| -|**/nosymbols**|In .NET Framework version 2.0, suppresses line numbers for backward compatibility.| -|**/quiet**|Specifies quiet mode; suppresses output of the verification problem reports. Peverify.exe still reports whether the file is type safe, but does not report information on problems preventing type safety verification.| -|`/transparent`|Verify only the transparent methods.| -|**/unique**|Ignores repeating error codes.| -|**/verbose**|In .NET Framework version 2.0, displays additional information in MSIL verification messages.| -|**/?**|Displays command syntax and options for the tool.| - -## Remarks - - The common language runtime relies on the type-safe execution of application code to help enforce security and isolation mechanisms. Normally, code that is not [verifiably type safe](../../standard/security/key-security-concepts.md#type-safety-and-security) cannot run, although you can set security policy to allow the execution of trusted but unverifiable code. - - If neither the **/md** nor **/il** options are specified, Peverify.exe performs both types of checks. Peverify.exe performs **/md** checks first. If there are no errors, **/il** checks are made. If you specify both **/md** and **/il**, **/il** checks are made even if there are errors in the metadata. Thus, if there are no metadata errors, **peverify** *filename* is equivalent to **peverify** *filename* **/md** **/il**. - - Peverify.exe performs comprehensive MSIL verification checks based on dataflow analysis plus a list of several hundred rules on valid metadata. For detailed information on the checks Peverify.exe performs, see the "Metadata Validation Specification" and the "MSIL Instruction Set Specification" in the Tools Developers Guide folder in the Windows SDK. - -.NET Framework version 2.0 or later supports verifiable `byref` returns specified using the following MSIL instructions: `dup`, `ldsflda`, `ldflda`, `ldelema`, `call`, and `unbox`. - -## Examples - - The following command performs metadata validation checks and MSIL type safety verification checks for methods implemented in the assembly `myAssembly.exe`. - -```console -peverify myAssembly.exe /md /il -``` - - Upon successful completion of the above request, Peverify.exe displays the following message. - + +## Syntax + +```console +peverify filename [options] +``` + +## Parameters + +|Argument|Description| +|--------------|-----------------| +|*filename*|The portable executable (PE) file for which to check the MSIL and metadata.| + +|Option|Description| +|------------|-----------------| +|**/break=** *maxErrorCount*|Aborts verification after *maxErrorCount* errors.

This parameter is not supported in .NET Framework version 2.0 or later.| +|**/clock**|Measures and reports the following verification times in milliseconds:

**MD Val. cycle**
Metadata validation cycle

**MD Val. pure**
Metadata validation pure

**IL Ver. cycle**
Microsoft intermediate language (MSIL) verification cycle

**IL Ver pure**
MSIL verification pure

The **MD Val. cycle** and **IL Ver. cycle** times include the time required to perform necessary startup and shutdown procedures. The **MD Val. pure** and **IL Ver pure** times reflect the time required to perform the validation or verification only.| +|**/help**|Displays command syntax and options for the tool.| +|**/hresult**|Displays error codes in hexadecimal format.| +|**/ignore=** *hex.code* [, *hex.code*]|Ignores the specified error codes.| +|**/ignore=@** *responseFile*|Ignores the error codes listed in the specified response file.| +|**/il**|Performs MSIL type safety verification checks for methods implemented in the assembly specified by *filename*. The tool returns detailed descriptions for each problem found unless you specify the **/quiet** option.| +|**/md**|Performs metadata validation checks on the assembly specified by *filename*. This option walks the full metadata structure within the file and reports all validation problems encountered.| +|**/nologo**|Suppresses the display of product version and copyright information.| +|**/nosymbols**|In .NET Framework version 2.0, suppresses line numbers for backward compatibility.| +|**/quiet**|Specifies quiet mode; suppresses output of the verification problem reports. Peverify.exe still reports whether the file is type safe, but does not report information on problems preventing type safety verification.| +|`/transparent`|Verify only the transparent methods.| +|**/unique**|Ignores repeating error codes.| +|**/verbose**|In .NET Framework version 2.0, displays additional information in MSIL verification messages.| +|**/?**|Displays command syntax and options for the tool.| + +## Remarks + + The common language runtime relies on the type-safe execution of application code to help enforce security and isolation mechanisms. Normally, code that is not [verifiably type safe](../../standard/security/key-security-concepts.md#type-safety-and-security) cannot run, although you can set security policy to allow the execution of trusted but unverifiable code. + + If neither the **/md** nor **/il** options are specified, Peverify.exe performs both types of checks. Peverify.exe performs **/md** checks first. If there are no errors, **/il** checks are made. If you specify both **/md** and **/il**, **/il** checks are made even if there are errors in the metadata. Thus, if there are no metadata errors, **peverify** *filename* is equivalent to **peverify** *filename* **/md** **/il**. + + Peverify.exe performs comprehensive MSIL verification checks based on dataflow analysis plus a list of several hundred rules on valid metadata. For detailed information on the checks Peverify.exe performs, see the "Metadata Validation Specification" and the "MSIL Instruction Set Specification" in the Tools Developers Guide folder in the Windows SDK. + +.NET Framework version 2.0 or later supports verifiable `byref` returns specified using the following MSIL instructions: `dup`, `ldsflda`, `ldflda`, `ldelema`, `call`, and `unbox`. + +## Examples + + The following command performs metadata validation checks and MSIL type safety verification checks for methods implemented in the assembly `myAssembly.exe`. + +```console +peverify myAssembly.exe /md /il +``` + + Upon successful completion of the above request, Peverify.exe displays the following message. + ```output -All classes and methods in myAssembly.exe Verified -``` - - The following command performs metadata validation checks and MSIL type safety verification checks for methods implemented in the assembly `myAssembly.exe`. The tool displays the time required to perform these checks. - -```console -peverify myAssembly.exe /md /il /clock -``` - - Upon successful completion of the above request, Peverify.exe displays the following message. - +All classes and methods in myAssembly.exe Verified +``` + + The following command performs metadata validation checks and MSIL type safety verification checks for methods implemented in the assembly `myAssembly.exe`. The tool displays the time required to perform these checks. + +```console +peverify myAssembly.exe /md /il /clock +``` + + Upon successful completion of the above request, Peverify.exe displays the following message. + ```output -All classes and methods in myAssembly.exe Verified -Timing: Total run 320 msec - MD Val.cycle 40 msec - MD Val.pure 10 msec - IL Ver.cycle 270 msec - IL Ver.pure 230 msec -``` - - The following command performs metadata validation checks and MSIL type safety verification checks for methods implemented in the assembly `myAssembly.exe`. Peverify.exe stops, however, when it reaches the maximum error count of 100. The tool also ignores the specified error codes. - -```console -peverify myAssembly.exe /break=100 /ignore=0x12345678,0xABCD1234 -``` - - The following command produces the same result as the above previous example, but specifies the error codes to ignore in the response file `ignoreErrors.rsp`. - -```console -peverify myAssembly.exe /break=100 /ignore@ignoreErrors.rsp -``` - - The response file can contain a comma-separated list of error codes. - +All classes and methods in myAssembly.exe Verified +Timing: Total run 320 msec + MD Val.cycle 40 msec + MD Val.pure 10 msec + IL Ver.cycle 270 msec + IL Ver.pure 230 msec +``` + + The following command performs metadata validation checks and MSIL type safety verification checks for methods implemented in the assembly `myAssembly.exe`. Peverify.exe stops, however, when it reaches the maximum error count of 100. The tool also ignores the specified error codes. + +```console +peverify myAssembly.exe /break=100 /ignore=0x12345678,0xABCD1234 +``` + + The following command produces the same result as the above previous example, but specifies the error codes to ignore in the response file `ignoreErrors.rsp`. + +```console +peverify myAssembly.exe /break=100 /ignore@ignoreErrors.rsp +``` + + The response file can contain a comma-separated list of error codes. + ```text -0x12345678, 0xABCD1234 -``` - - Alternatively, the response file can be formatted with one error code per line. - +0x12345678, 0xABCD1234 +``` + + Alternatively, the response file can be formatted with one error code per line. + ```text -0x12345678 -0xABCD1234 -``` - +0x12345678 +0xABCD1234 +``` + ## See also - [Tools](index.md) diff --git a/docs/framework/tools/sos-dll-sos-debugging-extension.md b/docs/framework/tools/sos-dll-sos-debugging-extension.md index 8662e61ad23c7..71fc3b9ba7de3 100644 --- a/docs/framework/tools/sos-dll-sos-debugging-extension.md +++ b/docs/framework/tools/sos-dll-sos-debugging-extension.md @@ -35,7 +35,7 @@ The SOS debugging extension (SOS.dll) helps you debug managed programs in Visual |**DumpClass** \<*EEClass address*>|Displays information about the `EEClass` structure associated with a type.

The **DumpClass** command displays static field values but does not display nonstatic field values.

Use the **DumpMT**, **DumpObj**, **Name2EE**, or **Token2EE** command to get an `EEClass` structure address.| |**DumpDomain** [\<*domain address*>]|Enumerates each object that is loaded within the specified object address. When called with no parameters, the **DumpDomain** command lists all objects in a process.| |**DumpHeap** [**-stat**] [**-strings**] [**-short**] [**-min** \<*size*>] [**-max** \<*size*>] [**-thinlock**] [**-startAtLowerBound**] [**-mt** \<*MethodTable address*>] [**-type** \<*partial type name*>] [*start* [*end*]]|Displays information about the garbage-collected heap and collection statistics about objects.

The **DumpHeap** command displays a warning if it detects excessive fragmentation in the garbage collector heap.

The **-stat** option restricts the output to the statistical type summary.

The **-strings** option restricts the output to a statistical string value summary.

The **-short** option limits output to just the address of each object. This lets you easily pipe output from the command to another debugger command for automation.

The **-min** option ignores objects that are less than the `size` parameter, specified in bytes (hex).

The **-max** option ignores objects that are larger than the `size` parameter, specified in bytes (hex).

The **-thinlock** option reports ThinLocks. For more information, see the **SyncBlk** command.

The `-startAtLowerBound` option forces the heap walk to begin at the lower bound of a supplied address range. During the planning phase, the heap is often not walkable because objects are being moved. This option forces **DumpHeap** to begin its walk at the specified lower bound. You must supply the address of a valid object as the lower bound for this option to work. You can display memory at the address of a bad object to manually find the next method table. If the garbage collection is currently in a call to `memcopy`, you may also be able to find the address of the next object by adding the size to the start address, which is supplied as a parameter.

The **-mt** option lists only those objects that correspond to the specified `MethodTable` structure.

The **-type** option lists only those objects whose type name is a substring match of the specified string.

The `start` parameter begins listing from the specified address.

The `end` parameter stops listing at the specified address.| -|**DumpIL** \<*Managed DynamicMethod object*> | \<*DynamicMethodDesc pointer*> | \<*MethodDesc pointer*>|Displays the Microsoft intermediate language (MSIL) that is associated with a managed method.

Note that dynamic MSIL is emitted differently than MSIL that is loaded from an assembly. Dynamic MSIL refers to objects in a managed object array rather than to metadata tokens.| +|**DumpIL** \<*Managed DynamicMethod object*> | \<*DynamicMethodDesc pointer*> | \<*MethodDesc pointer*>|Displays the common intermediate language (CIL) that is associated with a managed method.

Note that dynamic CIL is emitted differently than CIL that is loaded from an assembly. Dynamic CIL refers to objects in a managed object array rather than to metadata tokens.| |**DumpLog** [**-addr** \<*addressOfStressLog*>] [<*Filenam*`e`>]|Writes the contents of an in-memory stress log to the specified file. If you do not specify a name, this command creates a file called StressLog.txt in the current directory.

The in-memory stress log helps you diagnose stress failures without using locks or I/O. To enable the stress log, set the following registry keys under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\\.NETFramework:

(DWORD) StressLog = 1

(DWORD) LogFacility = 0xffffffff

(DWORD) StressLogSize = 65536

The optional `-addr` option lets you specify a stress log other than the default log.| |**DumpMD** \<*MethodDesc address*>|Displays information about a `MethodDesc` structure at the specified address.

You can use the **IP2MD** command to get the `MethodDesc` structure address from a managed function.| |**DumpMT** [**-MD**] \<*MethodTable address*>|Displays information about a method table at the specified address. Specifying the **-MD** option displays a list of all methods defined with the object.

Each managed object contains a method table pointer.| diff --git a/docs/framework/unmanaged-api/constants-unmanaged-api-reference.md b/docs/framework/unmanaged-api/constants-unmanaged-api-reference.md index 8f60c7be358d4..957214acc91fe 100644 --- a/docs/framework/unmanaged-api/constants-unmanaged-api-reference.md +++ b/docs/framework/unmanaged-api/constants-unmanaged-api-reference.md @@ -2,7 +2,7 @@ description: "Learn more about: Constants (Unmanaged API Reference)" title: "Constants (Unmanaged API Reference)" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "constants for unmanaged API [.NET Framework]" - "native API reference [.NET Framework], constants" - "unmanaged API reference [.NET Framework], constants" @@ -10,43 +10,43 @@ ms.assetid: 77526f65-b71c-4483-9d19-3a3751fd8a45 --- # Constants (Unmanaged API Reference) -This topic describes the language type, language vendor, and document type constants that are defined in CorSym.idl. - -## Language Type Constants - - The following table shows language type constants, which represent GUIDs that identify programming languages. - -|Symbol|Description| -|------------|-----------------| -|CorSym_LanguageType_C|Indicates the C language.| -|CorSym_LanguageType_CPlusPlus|Indicates the C++ language.| -|CorSym_LanguageType_CSharp|Indicates the C# language.| -|CorSym_LanguageType_Basic|Indicates the Basic language.| -|CorSym_LanguageType_Java|Indicates the Java language.| -|CorSym_LanguageType_Cobol|Indicates the COBOL language.| -|CorSym_LanguageType_Pascal|Indicates the Pascal language.| -|CorSym_LanguageType_ILAssembly|Indicates the Microsoft intermediate language (MSIL) assembly code.| -|CorSym_LanguageType_JScript|Indicates the JScript language.| -|CorSym_LanguageType_SMC|Indicates the SMC language.| -|CorSym_LanguageType_MCPlusPlus|Indicates the C++ language enabled for the .NET Framework.| - -## Language Vendor Constants - - The following table shows language vendor constants, which represent GUIDs that identify programming language vendors. - -|Symbol|Description| -|------------|-----------------| -|CorSym_LanguageVendor_Microsoft|Indicates Microsoft.| - -## Document Type Constants - - The following table shows document type constants, which represent GUIDs that identify document types. - -|Symbol|Description| -|------------|-----------------| -|CorSym_DocumentType_Text|Indicates a text document.| -|CorSym_DocumentType_MC|Indicates a non-text document.| - +This topic describes the language type, language vendor, and document type constants that are defined in CorSym.idl. + +## Language Type Constants + + The following table shows language type constants, which represent GUIDs that identify programming languages. + +|Symbol|Description| +|------------|-----------------| +|CorSym_LanguageType_C|Indicates the C language.| +|CorSym_LanguageType_CPlusPlus|Indicates the C++ language.| +|CorSym_LanguageType_CSharp|Indicates the C# language.| +|CorSym_LanguageType_Basic|Indicates the Basic language.| +|CorSym_LanguageType_Java|Indicates the Java language.| +|CorSym_LanguageType_Cobol|Indicates the COBOL language.| +|CorSym_LanguageType_Pascal|Indicates the Pascal language.| +|CorSym_LanguageType_ILAssembly|Indicates the common intermediate language (CIL) assembly code.| +|CorSym_LanguageType_JScript|Indicates the JScript language.| +|CorSym_LanguageType_SMC|Indicates the SMC language.| +|CorSym_LanguageType_MCPlusPlus|Indicates the C++ language enabled for the .NET Framework.| + +## Language Vendor Constants + + The following table shows language vendor constants, which represent GUIDs that identify programming language vendors. + +|Symbol|Description| +|------------|-----------------| +|CorSym_LanguageVendor_Microsoft|Indicates Microsoft.| + +## Document Type Constants + + The following table shows document type constants, which represent GUIDs that identify document types. + +|Symbol|Description| +|------------|-----------------| +|CorSym_DocumentType_Text|Indicates a text document.| +|CorSym_DocumentType_MC|Indicates a non-text document.| + ## See also - [Unmanaged API Reference](index.md) diff --git a/docs/framework/unmanaged-api/debugging/cor-active-function-structure.md b/docs/framework/unmanaged-api/debugging/cor-active-function-structure.md index fe17b8272d93a..e73ae5abc9787 100644 --- a/docs/framework/unmanaged-api/debugging/cor-active-function-structure.md +++ b/docs/framework/unmanaged-api/debugging/cor-active-function-structure.md @@ -2,56 +2,56 @@ description: "Learn more about: COR_ACTIVE_FUNCTION Structure" title: "COR_ACTIVE_FUNCTION Structure" ms.date: "03/30/2017" -api_name: +api_name: - "COR_ACTIVE_FUNCTION" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "COR_ACTIVE_FUNCTION" -helpviewer_keywords: +helpviewer_keywords: - "COR_ACTIVE_FUNCTION structure [.NET Framework debugging]" ms.assetid: ed86185f-2152-459c-961f-10c06d62e83f -topic_type: +topic_type: - "apiref" --- # COR_ACTIVE_FUNCTION Structure -Contains information about the functions that are currently active in a thread's frames. This structure is used by the [ICorDebugThread2::GetActiveFunctions](icordebugthread2-getactivefunctions-method.md) method. - -## Syntax - -```cpp -typedef struct _COR_ACTIVE_FUNCTION { - ICorDebugAppDomain *pAppDomain; - ICorDebugModule *pModule; - ICorDebugFunction2 *pFunction; - ULONG32 ilOffset; - ULONG32 flags; -} COR_ACTIVE_FUNCTION; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`pAppDomain`|Pointer to the application domain owner of the `ilOffset` field.| -|`pModule`|Pointer to the module owner of the `ilOffset` field.| -|`pFunction`|Pointer to the function owner of the `ilOffset` field.| -|`ilOffset`|The Microsoft intermediate language (MSIL) offset of the frame.| -|`flags`|Reserved for future extensibility.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Contains information about the functions that are currently active in a thread's frames. This structure is used by the [ICorDebugThread2::GetActiveFunctions](icordebugthread2-getactivefunctions-method.md) method. + +## Syntax + +```cpp +typedef struct _COR_ACTIVE_FUNCTION { + ICorDebugAppDomain *pAppDomain; + ICorDebugModule *pModule; + ICorDebugFunction2 *pFunction; + ULONG32 ilOffset; + ULONG32 flags; +} COR_ACTIVE_FUNCTION; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`pAppDomain`|Pointer to the application domain owner of the `ilOffset` field.| +|`pModule`|Pointer to the module owner of the `ilOffset` field.| +|`pFunction`|Pointer to the function owner of the `ilOffset` field.| +|`ilOffset`|The common intermediate language (CIL) offset of the frame.| +|`flags`|Reserved for future extensibility.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [Debugging Structures](debugging-structures.md) diff --git a/docs/framework/unmanaged-api/debugging/cor-debug-il-to-native-map-structure.md b/docs/framework/unmanaged-api/debugging/cor-debug-il-to-native-map-structure.md index f57099ce88a60..df8e4fb1ec58a 100644 --- a/docs/framework/unmanaged-api/debugging/cor-debug-il-to-native-map-structure.md +++ b/docs/framework/unmanaged-api/debugging/cor-debug-il-to-native-map-structure.md @@ -2,52 +2,52 @@ description: "Learn more about: COR_DEBUG_IL_TO_NATIVE_MAP Structure" title: "COR_DEBUG_IL_TO_NATIVE_MAP Structure" ms.date: "03/30/2017" -api_name: +api_name: - "COR_DEBUG_IL_TO_NATIVE_MAP" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "COR_DEBUG_IL_TO_NATIVE_MAP" -helpviewer_keywords: +helpviewer_keywords: - "COR_DEBUG_IL_TO_NATIVE_MAP structure [.NET Framework debugging]" ms.assetid: 06f3b504-085f-4142-934a-25381fe23d4c -topic_type: +topic_type: - "apiref" --- # COR_DEBUG_IL_TO_NATIVE_MAP Structure -Contains the offsets that are used to map Microsoft intermediate language (MSIL) code to native code. - -## Syntax - -```cpp -typedef struct COR_DEBUG_IL_TO_NATIVE_MAP { - ULONG32 ilOffset; - ULONG32 nativeStartOffset; - ULONG32 nativeEndOffset; -} COR_DEBUG_IL_TO_NATIVE_MAP; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`ilOffset`|The offset of the MSIL code.| -|`nativeStartOffset`|The offset of the start of the native code.| -|`nativeEndOffset`|The offset of the end of the native code.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorDebug.idl - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +Contains the offsets that are used to map common intermediate language (CIL) code to native code. + +## Syntax + +```cpp +typedef struct COR_DEBUG_IL_TO_NATIVE_MAP { + ULONG32 ilOffset; + ULONG32 nativeStartOffset; + ULONG32 nativeEndOffset; +} COR_DEBUG_IL_TO_NATIVE_MAP; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`ilOffset`|The offset of the CIL code.| +|`nativeStartOffset`|The offset of the start of the native code.| +|`nativeEndOffset`|The offset of the end of the native code.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorDebug.idl + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [GetILToNativeMapping Method](../profiling/icorprofilerinfo-getiltonativemapping-method.md) diff --git a/docs/framework/unmanaged-api/debugging/cor-il-map-structure.md b/docs/framework/unmanaged-api/debugging/cor-il-map-structure.md index 4b5c83666ea5e..6090f9f6223e1 100644 --- a/docs/framework/unmanaged-api/debugging/cor-il-map-structure.md +++ b/docs/framework/unmanaged-api/debugging/cor-il-map-structure.md @@ -2,90 +2,90 @@ description: "Learn more about: COR_IL_MAP Structure" title: "COR_IL_MAP Structure" ms.date: "03/30/2017" -api_name: +api_name: - "COR_IL_MAP" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "COR_IL_MAP" -helpviewer_keywords: +helpviewer_keywords: - "COR_IL_MAP structure [.NET Framework debugging]" ms.assetid: 534ebc17-963d-4b26-8375-8cd940281db3 -topic_type: +topic_type: - "apiref" --- # COR_IL_MAP Structure -Specifies changes in the relative offset of a function. - -## Syntax - -```cpp -typedef struct _COR_IL_MAP { +Specifies changes in the relative offset of a function. + +## Syntax + +```cpp +typedef struct _COR_IL_MAP { ULONG32 oldOffset; ULONG32 newOffset; - BOOL fAccurate; -} COR_IL_MAP; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`oldOffset`|The old Microsoft intermediate language (MSIL) offset relative to the beginning of the function.| -|`newOffset`|The new MSIL offset relative to the beginning of the function.| -|`fAccurate`|`true` if the mapping is known to be accurate; otherwise, `false`.| - -## Remarks - - The format of the map is as follows: The debugger will assume that `oldOffset` refers to an MSIL offset within the original, unmodified MSIL code. The `newOffset` parameter refers to the corresponding MSIL offset within the new, instrumented code. - - For stepping to work properly, the following requirements should be met: - -- The map should be sorted in ascending order. - -- Instrumented MSIL code should not be reordered. - -- Original MSIL code should not be removed. - -- The map should include entries to map all the sequence points from the program database (PDB) file. - - The map does not interpolate missing entries. The following example shows a map and its results. - - Map: - -- 0 old offset, 0 new offset - -- 5 old offset, 10 new offset - -- 9 old offset, 20 new offset - - Results: - -- An old offset of 0, 1, 2, 3, or 4 will be mapped to a new offset of 0. - -- An old offset of 5, 6, 7, or 8 will be mapped to new offset 10. - -- An old offset of 9 or higher will be mapped to new offset 20. - -- A new offset of 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9 will be mapped to old offset 0. - -- A new offset of 10, 11, 12, 13, 14, 15, 16, 17, 18, or 19 will be mapped to old offset 5. - -- A new offset of 20 or higher will be mapped to old offset 9. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorProf.idl - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - + BOOL fAccurate; +} COR_IL_MAP; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`oldOffset`|The old common intermediate language (CIL) offset relative to the beginning of the function.| +|`newOffset`|The new CIL offset relative to the beginning of the function.| +|`fAccurate`|`true` if the mapping is known to be accurate; otherwise, `false`.| + +## Remarks + + The format of the map is as follows: The debugger will assume that `oldOffset` refers to an CIL offset within the original, unmodified CIL code. The `newOffset` parameter refers to the corresponding CIL offset within the new, instrumented code. + + For stepping to work properly, the following requirements should be met: + +- The map should be sorted in ascending order. + +- Instrumented CIL code should not be reordered. + +- Original CIL code should not be removed. + +- The map should include entries to map all the sequence points from the program database (PDB) file. + + The map does not interpolate missing entries. The following example shows a map and its results. + + Map: + +- 0 old offset, 0 new offset + +- 5 old offset, 10 new offset + +- 9 old offset, 20 new offset + + Results: + +- An old offset of 0, 1, 2, 3, or 4 will be mapped to a new offset of 0. + +- An old offset of 5, 6, 7, or 8 will be mapped to new offset 10. + +- An old offset of 9 or higher will be mapped to new offset 20. + +- A new offset of 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9 will be mapped to old offset 0. + +- A new offset of 10, 11, 12, 13, 14, 15, 16, 17, 18, or 19 will be mapped to old offset 5. + +- A new offset of 20 or higher will be mapped to old offset 9. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorProf.idl + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [Debugging Structures](debugging-structures.md) diff --git a/docs/framework/unmanaged-api/debugging/cordebugmappingresult-enumeration.md b/docs/framework/unmanaged-api/debugging/cordebugmappingresult-enumeration.md index 2cd4d5c77caeb..728cbebcbfb56 100644 --- a/docs/framework/unmanaged-api/debugging/cordebugmappingresult-enumeration.md +++ b/docs/framework/unmanaged-api/debugging/cordebugmappingresult-enumeration.md @@ -2,62 +2,62 @@ description: "Learn more about: CorDebugMappingResult Enumeration" title: "CorDebugMappingResult Enumeration" ms.date: "03/30/2017" -api_name: +api_name: - "CorDebugMappingResult" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "CorDebugMappingResult" -helpviewer_keywords: +helpviewer_keywords: - "CorDebugMappingResult enumeration [.NET Framework debugging]" ms.assetid: 701281dd-2936-45c8-a1f0-3bf7332b093b -topic_type: +topic_type: - "apiref" --- # CorDebugMappingResult Enumeration -Provides the details of how the value of the instruction pointer (IP) was obtained. - -## Syntax - -```cpp -typedef enum CorDebugMappingResult { - MAPPING_PROLOG = 0x1, - MAPPING_EPILOG = 0x2, - MAPPING_NO_INFO = 0x4, - MAPPING_UNMAPPED_ADDRESS = 0x8, - MAPPING_EXACT = 0x10, - MAPPING_APPROXIMATE = 0x20, -} CorDebugMappingResult; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`MAPPING_PROLOG`|The native code is in the prolog, so the value of the IP is 0.| -|`MAPPING_EPILOG`|The native code is in an epilog, so the value of the IP is the address of the last instruction of the method.| -|`MAPPING_NO_INFO`|No mapping information is available for the method, so the value of the IP is 0.| -|`MAPPING_UNMAPPED_ADDRESS`|Although there is mapping information for the method, the current address cannot be mapped to Microsoft intermediate language (MSIL) code. The value of the IP is 0.| -|`MAPPING_EXACT`|Either the method maps exactly to MSIL code or the frame has been interpreted, so the value of the IP is accurate.| -|`MAPPING_APPROXIMATE`|The method was successfully mapped, but the value of the IP may be approximate.| - -## Remarks - - You can use the [ICorDebugILFrame::GetIP](icordebugilframe-getip-method.md) method to obtain the value of the instruction pointer. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +Provides the details of how the value of the instruction pointer (IP) was obtained. + +## Syntax + +```cpp +typedef enum CorDebugMappingResult { + MAPPING_PROLOG = 0x1, + MAPPING_EPILOG = 0x2, + MAPPING_NO_INFO = 0x4, + MAPPING_UNMAPPED_ADDRESS = 0x8, + MAPPING_EXACT = 0x10, + MAPPING_APPROXIMATE = 0x20, +} CorDebugMappingResult; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`MAPPING_PROLOG`|The native code is in the prolog, so the value of the IP is 0.| +|`MAPPING_EPILOG`|The native code is in an epilog, so the value of the IP is the address of the last instruction of the method.| +|`MAPPING_NO_INFO`|No mapping information is available for the method, so the value of the IP is 0.| +|`MAPPING_UNMAPPED_ADDRESS`|Although there is mapping information for the method, the current address cannot be mapped to common intermediate language (CIL) code. The value of the IP is 0.| +|`MAPPING_EXACT`|Either the method maps exactly to CIL code or the frame has been interpreted, so the value of the IP is accurate.| +|`MAPPING_APPROXIMATE`|The method was successfully mapped, but the value of the IP may be approximate.| + +## Remarks + + You can use the [ICorDebugILFrame::GetIP](icordebugilframe-getip-method.md) method to obtain the value of the instruction pointer. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [Debugging Enumerations](debugging-enumerations.md) diff --git a/docs/framework/unmanaged-api/debugging/debugging-interfaces.md b/docs/framework/unmanaged-api/debugging/debugging-interfaces.md index f14467603f1cd..5109173db3228 100644 --- a/docs/framework/unmanaged-api/debugging/debugging-interfaces.md +++ b/docs/framework/unmanaged-api/debugging/debugging-interfaces.md @@ -2,7 +2,7 @@ description: "Learn more about: Debugging Interfaces" title: "Debugging Interfaces" ms.date: "02/07/2019" -helpviewer_keywords: +helpviewer_keywords: - "unmanaged interfaces [.NET Framework], debugging" - "debugging interfaces [.NET Framework]" - "interfaces [.NET Framework debugging]" @@ -10,432 +10,432 @@ ms.assetid: b6297c26-7624-4431-8af4-14112d07bcd5 --- # Debugging Interfaces -This section describes the unmanaged interfaces that handle the debugging of a program that is executing in the common language runtime (CLR). - -## In This Section +This section describes the unmanaged interfaces that handle the debugging of a program that is executing in the common language runtime (CLR). + +## In This Section [ICLRDataEnumMemoryRegions Interface](iclrdataenummemoryregions-interface.md)\ - Provides a method to enumerate regions of memory that are specified by callers. - + Provides a method to enumerate regions of memory that are specified by callers. + [ICLRDataEnumMemoryRegionsCallback Interface](iclrdataenummemoryregionscallback-interface.md)\ - Provides a callback method for `EnumMemoryRegions` to report to the debugger, the result of an attempt to enumerate a specified region of memory. - + Provides a callback method for `EnumMemoryRegions` to report to the debugger, the result of an attempt to enumerate a specified region of memory. + [ICLRDataTarget Interface](iclrdatatarget-interface.md)\ - Provides methods for interaction with a target CLR process. - + Provides methods for interaction with a target CLR process. + [ICLRDataTarget2 Interface](iclrdatatarget2-interface.md)\ - A subclass of `ICLRDataTarget` that is used by the data access services layer to manipulate virtual memory regions in the target process. - + A subclass of `ICLRDataTarget` that is used by the data access services layer to manipulate virtual memory regions in the target process. + [ICLRDataTarget3 Interface](iclrdatatarget3-interface.md)\ - A subclass of [ICLRDataTarget2](iclrdatatarget2-interface.md) that provides access to exception information. - + A subclass of [ICLRDataTarget2](iclrdatatarget2-interface.md) that provides access to exception information. + [ICLRDebugging Interface](iclrdebugging-interface.md)\ - Provides methods that handle loading and unloading modules for debugging. - + Provides methods that handle loading and unloading modules for debugging. + [ICLRDebuggingLibraryProvider Interface](iclrdebugginglibraryprovider-interface.md)\ - Includes the [ProvideLibrary Method](iclrdebugginglibraryprovider-providelibrary-method.md) method, which gets a library provider callback interface that allows common language runtime version-specific debugging libraries to be located and loaded on demand. - + Includes the [ProvideLibrary Method](iclrdebugginglibraryprovider-providelibrary-method.md) method, which gets a library provider callback interface that allows common language runtime version-specific debugging libraries to be located and loaded on demand. + [ICLRMetadataLocator Interface](iclrmetadatalocator-interface.md)\ - Interface used by the data access services layer to locate metadata of assemblies in a target process. - + Interface used by the data access services layer to locate metadata of assemblies in a target process. + [ICorDebug Interface](icordebug-interface.md)\ - Provides methods that allow developers to debug applications in the CLR environment. - + Provides methods that allow developers to debug applications in the CLR environment. + [ICorDebugAppDomain Interface](icordebugappdomain-interface.md)\ - Provides methods for debugging application domains. - + Provides methods for debugging application domains. + [ICorDebugAppDomain2 Interface](icordebugappdomain2-interface.md)\ - Provides methods to work with arrays, pointers, function pointers, and ByRef types. This interface is an extension of the `ICorDebugAppDomain` interface. - + Provides methods to work with arrays, pointers, function pointers, and ByRef types. This interface is an extension of the `ICorDebugAppDomain` interface. + [ICorDebugAppDomain3 Interface](icordebugappdomain3-interface.md)\ - Provides methods to work with the Windows Runtime types in an application domain. This interface is an extension of the `ICorDebugAppDomain` and `ICorDebugAppDomain2` interfaces. - + Provides methods to work with the Windows Runtime types in an application domain. This interface is an extension of the `ICorDebugAppDomain` and `ICorDebugAppDomain2` interfaces. + [ICorDebugAppDomain4 Interface](icordebugappdomain4-interface.md)\ - Logically extends the [ICorDebugAppDomain](icordebugappdomain-interface.md) interface to get a managed object from a COM callable wrapper. - + Logically extends the [ICorDebugAppDomain](icordebugappdomain-interface.md) interface to get a managed object from a COM callable wrapper. + [ICorDebugAppDomainEnum Interface](icordebugappdomainenum-interface.md)\ - Provides a method that returns a specified number of `ICorDebugAppDomain` values starting at the next location in the enumeration. - + Provides a method that returns a specified number of `ICorDebugAppDomain` values starting at the next location in the enumeration. + [ICorDebugArrayValue Interface](icordebugarrayvalue-interface.md)\ - A subclass of `ICorDebugHeapValue` that represents a single-dimensional or multi-dimensional array. - + A subclass of `ICorDebugHeapValue` that represents a single-dimensional or multi-dimensional array. + [ICorDebugAssembly Interface](icordebugassembly-interface.md)\ - Represents an assembly. - + Represents an assembly. + [ICorDebugAssembly2 Interface](icordebugassembly2-interface.md)\ - Represents an assembly. This interface is an extension of the `ICorDebugAssembly` interface. - + Represents an assembly. This interface is an extension of the `ICorDebugAssembly` interface. + [ICorDebugAssembly3 Interface](icordebugassembly3-interface.md)\ - Logically extends the [ICorDebugAssembly](icordebugassembly-interface.md) interface to provide support for container assemblies and their contained assemblies. **Available on .NET Native only.** - + Logically extends the [ICorDebugAssembly](icordebugassembly-interface.md) interface to provide support for container assemblies and their contained assemblies. **Available on .NET Native only.** + [ICorDebugAssemblyEnum Interface](icordebugassemblyenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugAssembly` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugAssembly` arrays. + [ICorDebugBlockingObjectEnum Interface](icordebugblockingobjectenum-interface.md)\ - Provides an enumerator for a list of [CorDebugBlockingObject](cordebugblockingobject-structure.md) structures. - + Provides an enumerator for a list of [CorDebugBlockingObject](cordebugblockingobject-structure.md) structures. + [ICorDebugBoxValue Interface](icordebugboxvalue-interface.md)\ - A subclass of `ICorDebugHeapValue` that represents a boxed value class object. - + A subclass of `ICorDebugHeapValue` that represents a boxed value class object. + [ICorDebugBreakpoint Interface](icordebugbreakpoint-interface.md)\ - Represents a breakpoint in a function or a watch point on a value. - + Represents a breakpoint in a function or a watch point on a value. + [ICorDebugBreakpointEnum Interface](icordebugbreakpointenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugBreakpoint` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugBreakpoint` arrays. + [ICorDebugChain Interface](icordebugchain-interface.md)\ - Represents a segment of a physical or logical call stack. - + Represents a segment of a physical or logical call stack. + [ICorDebugChainEnum Interface](icordebugchainenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugChain` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugChain` arrays. + [ICorDebugClass Interface](icordebugclass-interface.md)\ - Represents a type, which can be either basic or complex (that is, user-defined). If the type is generic, `ICorDebugClass` represents the uninstantiated generic type. - + Represents a type, which can be either basic or complex (that is, user-defined). If the type is generic, `ICorDebugClass` represents the uninstantiated generic type. + [ICorDebugClass2 Interface](icordebugclass2-interface.md)\ - Represents a generic class or a class with a method parameter of type . This interface extends `ICorDebugClass`. - + Represents a generic class or a class with a method parameter of type . This interface extends `ICorDebugClass`. + [ICorDebugCode Interface](icordebugcode-interface1.md)\ - Represents a segment of either Microsoft intermediate language (MSIL) code or native code. - + Represents a segment of either common intermediate language (CIL) code or native code. + [ICorDebugCode2 Interface](icordebugcode2-interface.md)\ - Provides methods that extend the capabilities of `ICorDebugCode`. - + Provides methods that extend the capabilities of `ICorDebugCode`. + [ICorDebugCode3 Interface](icordebugcode3-interface.md)\ - Provides a method that extends [ICorDebugCode](icordebugcode-interface1.md) and [ICorDebugCode2](icordebugcode2-interface.md) to provide information about a managed return value. - + Provides a method that extends [ICorDebugCode](icordebugcode-interface1.md) and [ICorDebugCode2](icordebugcode2-interface.md) to provide information about a managed return value. + [ICorDebugCode4 Interface](icordebugcode4-interface.md)\ - Provides a method that enables a debugger to enumerate the local variables and arguments in a function. - + Provides a method that enables a debugger to enumerate the local variables and arguments in a function. + [ICorDebugCodeEnum Interface](icordebugcodeenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugCode` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugCode` arrays. + [ICorDebugComObjectValue Interface](icordebugcomobjectvalue-interface.md)\ - Provides methods to retrieve cached interface objects. - + Provides methods to retrieve cached interface objects. + [ICorDebugContext Interface](icordebugcontext-interface.md)\ - Represents a context object. This interface has not been implemented yet. - + Represents a context object. This interface has not been implemented yet. + [ICorDebugController Interface](icordebugcontroller-interface.md)\ - Represents a scope, either a or an , in which code execution context can be controlled. - + Represents a scope, either a or an , in which code execution context can be controlled. + [ICorDebugDataTarget Interface](icordebugdatatarget-interface.md)\ - Provides a callback interface that provides access to a particular target process. - + Provides a callback interface that provides access to a particular target process. + [ICorDebugDataTarget2 Interface](icordebugdatatarget2-interface.md)\ - Logically extends the [ICorDebugDataTarget](icordebugdatatarget-interface.md) interface. **Available on .NET Native only.** - + Logically extends the [ICorDebugDataTarget](icordebugdatatarget-interface.md) interface. **Available on .NET Native only.** + [ICorDebugDataTarget3 Interface](icordebugdatatarget3-interface.md)\ - Logically extends the [ICorDebugDataTarget](icordebugdatatarget-interface.md) interface to provide information about loaded modules. **Available on .NET Native only.** - + Logically extends the [ICorDebugDataTarget](icordebugdatatarget-interface.md) interface to provide information about loaded modules. **Available on .NET Native only.** + [ICorDebugDebugEvent Interface](icordebugdebugevent-interface.md)\ - Defines the base interface from which all `ICorDebug` debug events derive. **Available on .NET Native only.** - + Defines the base interface from which all `ICorDebug` debug events derive. **Available on .NET Native only.** + [ICorDebugEditAndContinueErrorInfo Interface](icordebugeditandcontinueerrorinfo-interface.md)\ - Obsolete. Do not use this interface. - + Obsolete. Do not use this interface. + [ICorDebugEditAndContinueSnapshot Interface](icordebugeditandcontinuesnapshot-interface.md)\ - Obsolete. Do not use this interface. - + Obsolete. Do not use this interface. + [ICorDebugEnum Interface](icordebugenum-interface1.md)\ - Serves as the abstract base interface for debugging enumerators. - + Serves as the abstract base interface for debugging enumerators. + [ICorDebugErrorInfoEnum Interface](icordebugerrorinfoenum-interface.md)\ - Obsolete. Do not use this interface. - + Obsolete. Do not use this interface. + [ICorDebugEval Interface](icordebugeval-interface.md)\ - Provides methods to enable the debugger to execute code within the context of the code being debugged. - + Provides methods to enable the debugger to execute code within the context of the code being debugged. + [ICorDebugEval2 Interface](icordebugeval2-interface.md)\ - Extends `ICorDebugEval` to provide support for generic types. - + Extends `ICorDebugEval` to provide support for generic types. + [ICorDebugExceptionDebugEvent Interface](icordebugexceptiondebugevent-interface.md)\ - Extends the [ICorDebugDebugEvent](icordebugdebugevent-interface.md) interface to support exception events. **Available on .NET Native only.** - + Extends the [ICorDebugDebugEvent](icordebugdebugevent-interface.md) interface to support exception events. **Available on .NET Native only.** + [ICorDebugExceptionObjectCallStackEnum Interface](icordebugexceptionobjectcallstackenum-interface.md)\ - Provides an enumerator for call stack information that is embedded in an exception object. - + Provides an enumerator for call stack information that is embedded in an exception object. + [ICorDebugExceptionObjectValue Interface](icordebugexceptionobjectvalue-interface.md)\ - Extends the [ICorDebugObjectValue](icordebugobjectvalue-interface.md) interface to provide stack trace information from a managed exception object. - + Extends the [ICorDebugObjectValue](icordebugobjectvalue-interface.md) interface to provide stack trace information from a managed exception object. + [ICorDebugFrame Interface](icordebugframe-interface.md)\ - Represents a frame on the current stack. - + Represents a frame on the current stack. + [ICorDebugFrameEnum Interface](icordebugframeenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugFrame` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugFrame` arrays. + [ICorDebugFunction Interface](icordebugfunction-interface1.md)\ - Represents a managed function or method. - + Represents a managed function or method. + [ICorDebugFunction2 Interface](icordebugfunction2-interface.md)\ - Logically extends `ICorDebugFunction` to provide support for Just My Code step-through debugging. - + Logically extends `ICorDebugFunction` to provide support for Just My Code step-through debugging. + [ICorDebugFunction3 Interface](icordebugfunction3-interface.md)\ - Logically extends the [ICorDebugFunction](icordebugfunction-interface1.md) interface to provide access to code from a ReJIT request. - + Logically extends the [ICorDebugFunction](icordebugfunction-interface1.md) interface to provide access to code from a ReJIT request. + [ICorDebugFunctionBreakpoint Interface](icordebugfunctionbreakpoint-interface.md)\ - Extends `ICorDebugBreakpoint` to support breakpoints within functions. - + Extends `ICorDebugBreakpoint` to support breakpoints within functions. + [ICorDebugGCReferenceEnum Interface](icordebuggcreferenceenum-interface.md)\ - Provides an enumerator for objects that will be garbage-collected. - + Provides an enumerator for objects that will be garbage-collected. + [ICorDebugGenericValue Interface](icordebuggenericvalue-interface.md)\ - A subclass of `ICorDebugValue` that applies to all values. This interface provides Get and Set methods for the value. - + A subclass of `ICorDebugValue` that applies to all values. This interface provides Get and Set methods for the value. + [ICorDebugGuidToTypeEnum Interface](icordebugguidtotypeenum-interface.md)\ - Provides an enumerator for an object that maps GUIDs and their corresponding `ICorDebugType` objects. - + Provides an enumerator for an object that maps GUIDs and their corresponding `ICorDebugType` objects. + [ICorDebugHandleValue Interface](icordebughandlevalue-interface.md)\ - A subclass of `ICorDebugReferenceValue` that represents a reference value to which the debugger has created a handle for garbage collection. - + A subclass of `ICorDebugReferenceValue` that represents a reference value to which the debugger has created a handle for garbage collection. + [ICorDebugHeapEnum Interface](icordebugheapenum-interface.md)\ - Provides an enumerator for objects on the managed heap. - + Provides an enumerator for objects on the managed heap. + [ICorDebugHeapSegmentEnum Interface](icordebugheapsegmentenum-interface.md)\ - Provides an enumerator for the memory regions of the managed heap. - + Provides an enumerator for the memory regions of the managed heap. + [ICorDebugHeapValue Interface](icordebugheapvalue-interface.md)\ - A subclass of `ICorDebugValue` that represents an object that has been collected by the CLR garbage collector. - + A subclass of `ICorDebugValue` that represents an object that has been collected by the CLR garbage collector. + [ICorDebugHeapValue2 Interface](icordebugheapvalue2-interface1.md)\ - An extension of `ICorDebugHeapValue` that provides support for runtime handles. - + An extension of `ICorDebugHeapValue` that provides support for runtime handles. + [ICorDebugHeapValue3 Interface](icordebugheapvalue3-interface.md)\ - Exposes the monitor lock properties of objects. - + Exposes the monitor lock properties of objects. + [ICorDebugILCode Interface](icordebugilcode-interface.md)\ - Represents a segment of intermediate language (IL) code. - + Represents a segment of intermediate language (IL) code. + [ICorDebugILCode2 Interface](icordebugilcode2-interface.md)\ - Logically extends the [ICorDebugILCode](icordebugilcode-interface.md) interface to provide methods that return the token for a function's local variable signature, and that map a profiler's instrumented intermediate language (IL) offsets to original method IL offsets. - + Logically extends the [ICorDebugILCode](icordebugilcode-interface.md) interface to provide methods that return the token for a function's local variable signature, and that map a profiler's instrumented intermediate language (IL) offsets to original method IL offsets. + [ICorDebugILFrame Interface](icordebugilframe-interface.md)\ - Represents a stack frame of MSIL code. - + Represents a stack frame of CIL code. + [ICorDebugILFrame2 Interface](icordebugilframe2-interface.md)\ - A logical extension of `ICorDebugILFrame`. - + A logical extension of `ICorDebugILFrame`. + [ICorDebugILFrame3 Interface](icordebugilframe3-interface.md)\ - Provides a method that encapsulates the return value of a function. - + Provides a method that encapsulates the return value of a function. + [ICorDebugILFrame4 Interface](icordebugilframe4-interface.md)\ - Provides methods that allow you to access the local variables and code in a stack frame of intermediate language (IL) code. A parameter specifies whether the debugger has access to variables and code added in profiler ReJIT instrumentation. - + Provides methods that allow you to access the local variables and code in a stack frame of intermediate language (IL) code. A parameter specifies whether the debugger has access to variables and code added in profiler ReJIT instrumentation. + [ICorDebugInstanceFieldSymbol Interface](icordebuginstancefieldsymbol-interface.md)\ - Represents the debug symbol information for an instance field. **Available on .NET Native only.** - + Represents the debug symbol information for an instance field. **Available on .NET Native only.** + [ICorDebugInternalFrame Interface](icordebuginternalframe-interface.md)\ - Identifies frame types for the debugger. - + Identifies frame types for the debugger. + [ICorDebugInternalFrame2 Interface](icordebuginternalframe2-interface.md)\ - Provides information about internal frames, including stack address and position in relation to [ICorDebugFrame](icordebugframe-interface.md) objects. - + Provides information about internal frames, including stack address and position in relation to [ICorDebugFrame](icordebugframe-interface.md) objects. + [ICorDebugLoadedModule Interface](icordebugloadedmodule-interface.md)\ - Provides information about a loaded module. **Available on .NET Native only.** - + Provides information about a loaded module. **Available on .NET Native only.** + [ICorDebugManagedCallback Interface](icordebugmanagedcallback-interface.md)\ - Provides methods to process debugger callbacks. - + Provides methods to process debugger callbacks. + [ICorDebugManagedCallback2 Interface](icordebugmanagedcallback2-interface.md)\ - Provides methods to support debugger exception handling and managed debugging assistants (MDAs). `ICorDebugManagedCallback2` is a logical extension of `ICorDebugManagedCallback`. - + Provides methods to support debugger exception handling and managed debugging assistants (MDAs). `ICorDebugManagedCallback2` is a logical extension of `ICorDebugManagedCallback`. + [ICorDebugManagedCallback3 Interface](icordebugmanagedcallback3-interface.md)\ - Provides a callback method that indicates that an enabled custom debugger notification has been raised. - + Provides a callback method that indicates that an enabled custom debugger notification has been raised. + [ICorDebugMDA Interface](icordebugmda-interface.md)\ - Represents a managed debugging assistant (MDA) message. - + Represents a managed debugging assistant (MDA) message. + [ICorDebugMemoryBuffer Interface](icordebugmemorybuffer-interface.md)\ - Represents an in-memory buffer. **Available on .NET Native only.** - + Represents an in-memory buffer. **Available on .NET Native only.** + [ICorDebugMergedAssemblyRecord Interface](icordebugmergedassemblyrecord-interface.md)\ - Provides information about a merged assembly. **Available on .NET Native only.** - + Provides information about a merged assembly. **Available on .NET Native only.** + [ICorDebugMetaDataLocator Interface](icordebugmetadatalocator-interface.md)\ - Provides metadata information to the debugger. - + Provides metadata information to the debugger. + [ICorDebugModule Interface](icordebugmodule-interface.md)\ - Represents a CLR module, which is either an executable or a dynamic-link library (DLL). - + Represents a CLR module, which is either an executable or a dynamic-link library (DLL). + [ICorDebugModule2 Interface](icordebugmodule2-interface.md)\ - Serves as a logical extension to `ICorDebugModule`. - + Serves as a logical extension to `ICorDebugModule`. + [ICorDebugModule3 Interface](icordebugmodule3-interface.md)\ - Creates a symbol reader for a dynamic module. + Creates a symbol reader for a dynamic module. [ICorDebugModule4 Interface](icordebugmodule4-interface.md)\ - Provides a method that determines whether the module is loaded into memory in mapped/hydrated format. - + Provides a method that determines whether the module is loaded into memory in mapped/hydrated format. + [ICorDebugModuleBreakpoint Interface](icordebugmodulebreakpoint-interface.md)\ - Extends `ICorDebugBreakpoint` to provide access to specific modules. - + Extends `ICorDebugBreakpoint` to provide access to specific modules. + [ICorDebugModuleDebugEvent Interface](icordebugmoduledebugevent-interface.md)\ - Extends the [ICorDebugDebugEvent](icordebugdebugevent-interface.md) interface to support module-level events. **Available on .NET Native only.** - + Extends the [ICorDebugDebugEvent](icordebugdebugevent-interface.md) interface to support module-level events. **Available on .NET Native only.** + [ICorDebugModuleEnum Interface](icordebugmoduleenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugModule` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugModule` arrays. + [ICorDebugMutableDataTarget Interface](icordebugmutabledatatarget-interface.md)\ - Extends the [ICorDebugDataTarget](icordebugdatatarget-interface.md) interface to support mutable data targets. - + Extends the [ICorDebugDataTarget](icordebugdatatarget-interface.md) interface to support mutable data targets. + [ICorDebugNativeFrame Interface](icordebugnativeframe-interface.md)\ - A specialized implementation of `ICorDebugFrame` used for native frames. - + A specialized implementation of `ICorDebugFrame` used for native frames. + [ICorDebugNativeFrame2 Interface](icordebugnativeframe2-interface.md)\ - Provides methods that test for child and parent frame relationships. - + Provides methods that test for child and parent frame relationships. + [ICorDebugObjectEnum Interface](icordebugobjectenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates arrays of objects by their relative virtual addresses (RVAs). - + Implements `ICorDebugEnum` methods, and enumerates arrays of objects by their relative virtual addresses (RVAs). + [ICorDebugObjectValue Interface](icordebugobjectvalue-interface.md)\ - A subclass of `ICorDebugValue` that represents a value that contains an object. - + A subclass of `ICorDebugValue` that represents a value that contains an object. + [ICorDebugObjectValue2 Interface](icordebugobjectvalue2-interface.md)\ - Extends `ICorDebugObjectValue` to support inheritance and overrides. - + Extends `ICorDebugObjectValue` to support inheritance and overrides. + [ICorDebugProcess Interface](icordebugprocess-interface.md)\ - Represents a process that is executing managed code. - + Represents a process that is executing managed code. + [ICorDebugProcess2 Interface](icordebugprocess2-interface1.md)\ - A logical extension of `ICorDebugProcess`. - + A logical extension of `ICorDebugProcess`. + [ICorDebugProcess3 Interface](icordebugprocess3-interface.md)\ Controls custom debugger notifications. [ICorDebugProcess4 Interface](icordebugprocess4-interface.md)\ Provides support for out of process execution control. - + [ICorDebugProcess5 Interface](icordebugprocess5-interface.md)\ - Extends the [ICorDebugProcess](icordebugprocess-interface.md) interface to support access to the managed heap, to provide information about garbage collection of managed objects, and to determine whether a debugger loads images from the application's local native image cache. - + Extends the [ICorDebugProcess](icordebugprocess-interface.md) interface to support access to the managed heap, to provide information about garbage collection of managed objects, and to determine whether a debugger loads images from the application's local native image cache. + [ICorDebugProcess6 Interface](icordebugprocess6-interface.md)\ - Logically extends the [ICorDebugProcess](icordebugprocess-interface.md) interface to enable features such as decoding managed debug events that are encoded in native exception debug events and virtual module splitting. **Available on .NET Native only.** - + Logically extends the [ICorDebugProcess](icordebugprocess-interface.md) interface to enable features such as decoding managed debug events that are encoded in native exception debug events and virtual module splitting. **Available on .NET Native only.** + [ICorDebugProcess7 Interface](icordebugprocess7-interface.md)\ - Provides a method that configures the debugger to handle in-memory metadata updates in the target process. - + Provides a method that configures the debugger to handle in-memory metadata updates in the target process. + [ICorDebugProcess8 Interface](icordebugprocess8-interface.md)\ - Logically extends the [ICorDebugProcess](icordebugprocess-interface.md) interface to enable or disable certain types of [ICorDebugManagedCallback2](icordebugmanagedcallback2-interface.md) exception callbacks. + Logically extends the [ICorDebugProcess](icordebugprocess-interface.md) interface to enable or disable certain types of [ICorDebugManagedCallback2](icordebugmanagedcallback2-interface.md) exception callbacks. [ICorDebugProcess11 Interface](icordebugprocess11-interface.md)\ - Provides a method that enumerates ranges of native memory that are used by the .NET runtime to store internal data structures that describe .NET types and methods. The information returned is the same information that would be shown by using the SOS `eeheap -loader` command. - + Provides a method that enumerates ranges of native memory that are used by the .NET runtime to store internal data structures that describe .NET types and methods. The information returned is the same information that would be shown by using the SOS `eeheap -loader` command. + [ICorDebugProcessEnum Interface](icordebugprocessenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugProcess` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugProcess` arrays. + [ICorDebugReferenceValue Interface](icordebugreferencevalue-interface.md)\ - A subclass of `ICorDebugValue` that supports reference types. - + A subclass of `ICorDebugValue` that supports reference types. + [ICorDebugRegisterSet Interface](icordebugregisterset-interface.md)\ - Represents the set of registers available on the machine that is currently executing code. - + Represents the set of registers available on the machine that is currently executing code. + [ICorDebugRegisterSet2 Interface](icordebugregisterset2-interface.md)\ - Extends the capabilities of `ICorDebugRegisterSet` for hardware platforms that have more than 64 registers. - + Extends the capabilities of `ICorDebugRegisterSet` for hardware platforms that have more than 64 registers. + [ICorDebugRemote Interface](icordebugremote-interface.md)\ - Provides the ability to launch or attach a managed debugger to a remote target process. - + Provides the ability to launch or attach a managed debugger to a remote target process. + [ICorDebugRemoteTarget Interface](icordebugremotetarget-interface.md)\ - Provides methods that enable you to debug Silverlight-based applications in the CLR environment. - + Provides methods that enable you to debug Silverlight-based applications in the CLR environment. + [ICorDebugRuntimeUnwindableFrame Interface](icordebugruntimeunwindableframe-interface.md)\ - Provides support for unmanaged methods that require the common language runtime (CLR) to unwind a frame. - + Provides support for unmanaged methods that require the common language runtime (CLR) to unwind a frame. + [ICorDebugStackWalk Interface](icordebugstackwalk-interface.md)\ - Provides methods for getting the managed methods, or frames, on a thread’s stack. - + Provides methods for getting the managed methods, or frames, on a thread’s stack. + [ICorDebugStaticFieldSymbol Interface](icordebugstaticfieldsymbol-interface.md)\ - Represents the debug symbol information for a static field. **Available on .NET Native only.** - + Represents the debug symbol information for a static field. **Available on .NET Native only.** + [ICorDebugStepper Interface](icordebugstepper-interface.md)\ - Represents a step in code execution that is performed by a debugger, serves as an identifier between the issuance and completion of a command, and provides a way to cancel a step. - + Represents a step in code execution that is performed by a debugger, serves as an identifier between the issuance and completion of a command, and provides a way to cancel a step. + [ICorDebugStepper2 Interface](icordebugstepper2-interface1.md)\ - Provides support for Just My Code (JMC) debugging. - + Provides support for Just My Code (JMC) debugging. + [ICorDebugStepperEnum Interface](icordebugstepperenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugStepper` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugStepper` arrays. + [ICorDebugStringValue Interface](icordebugstringvalue-interface.md)\ - A subclass of `ICorDebugHeapValue` that applies to string values. - + A subclass of `ICorDebugHeapValue` that applies to string values. + [ICorDebugSymbolProvider Interface](icordebugsymbolprovider-interface.md)\ - Provides methods that can be used to retrieve debug symbol information. **Available on .NET Native only.** - + Provides methods that can be used to retrieve debug symbol information. **Available on .NET Native only.** + [ICorDebugSymbolProvider2 Interface](icordebugsymbolprovider2-interface.md)\ - Logically extends the [ICorDebugSymbolProvider](icordebugsymbolprovider-interface.md) interface to retrieve additional debug symbol information. **Available on .NET Native only.** - + Logically extends the [ICorDebugSymbolProvider](icordebugsymbolprovider-interface.md) interface to retrieve additional debug symbol information. **Available on .NET Native only.** + [ICorDebugThread Interface](icordebugthread-interface.md)\ - Represents a thread in a process. The lifetime of an `ICorDebugThread` instance is the same as the lifetime of the thread it represents. - + Represents a thread in a process. The lifetime of an `ICorDebugThread` instance is the same as the lifetime of the thread it represents. + [ICorDebugThread2 Interface](icordebugthread2-interface.md)\ - Serves as a logical extension to `ICorDebugThread`. - + Serves as a logical extension to `ICorDebugThread`. + [ICorDebugThread3 Interface](icordebugthread3-interface.md)\ - Provides the entry point to the [ICorDebugStackWalk](icordebugstackwalk-interface.md) and corresponding interfaces. - + Provides the entry point to the [ICorDebugStackWalk](icordebugstackwalk-interface.md) and corresponding interfaces. + [ICorDebugThread4 Interface](icordebugthread4-interface.md)\ - Provides thread blocking information. - + Provides thread blocking information. + [ICorDebugThreadEnum Interface](icordebugthreadenum-interface1.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugThread` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugThread` arrays. + [ICorDebugType Interface](icordebugtype-interface.md)\ - Represents a type, which can be either basic or complex (that is, user-defined). If the type is generic, `ICorDebugType` represents the instantiated generic type. - + Represents a type, which can be either basic or complex (that is, user-defined). If the type is generic, `ICorDebugType` represents the instantiated generic type. + [ICorDebugType2 Interface](icordebugtype2-interface.md)\ - Extends the [ICorDebugType](icordebugtype-interface.md) interface to retrieve the type identifier of a base type or complex (user-defined) type. - + Extends the [ICorDebugType](icordebugtype-interface.md) interface to retrieve the type identifier of a base type or complex (user-defined) type. + [ICorDebugTypeEnum Interface](icordebugtypeenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugType` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugType` arrays. + [ICorDebugUnmanagedCallback Interface](icordebugunmanagedcallback-interface.md)\ - Provides notification of native events that are not directly related to the CLR. - + Provides notification of native events that are not directly related to the CLR. + [ICorDebugValue](icordebugvalue-interface.md)\ - Represents a read or write value in the process being debugged. - + Represents a read or write value in the process being debugged. + [ICorDebugValue2](icordebugvalue2-interface.md)\ - Extends `ICorDebugValue` to provide support for `ICorDebugType`. - + Extends `ICorDebugValue` to provide support for `ICorDebugType`. + [ICorDebugValue3 Interface](icordebugvalue3-interface.md)\ - Extends the "ICorDebugValue" and "ICorDebugValue2" interfaces to provide support for arrays that are larger than 2 GB. - + Extends the "ICorDebugValue" and "ICorDebugValue2" interfaces to provide support for arrays that are larger than 2 GB. + [ICorDebugValueBreakpoint](icordebugvaluebreakpoint-interface.md)\ - Extends `ICorDebugBreakpoint` to provide access to specific values. - + Extends `ICorDebugBreakpoint` to provide access to specific values. + [ICorDebugValueEnum](icordebugvalueenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugValue` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugValue` arrays. + [ICorDebugVariableHome Interface](icordebugvariablehome-interface.md)\ - Represents a local variable or argument of a function. - + Represents a local variable or argument of a function. + [ICorDebugVariableHomeEnum Interface](icordebugvariablehomeenum-interface.md)\ - Provides an enumerator to the local variables and arguments in a function. - + Provides an enumerator to the local variables and arguments in a function. + [ICorDebugVariableSymbol Interface](icordebugvariablesymbol-interface.md)\ - Retrieves the debug symbol information for a variable. **Available on .NET Native only.** - + Retrieves the debug symbol information for a variable. **Available on .NET Native only.** + [ICorDebugVirtualUnwinder Interface](icordebugvirtualunwinder-interface.md)\ - Provides methods to help in stack unwinding. **Available on .NET Native only.** - + Provides methods to help in stack unwinding. **Available on .NET Native only.** + [ICorPublish Interface](icorpublish-interface.md)\ - Serves as the general interface for the publishing processes. - + Serves as the general interface for the publishing processes. + [ICorPublishAppDomain Interface](icorpublishappdomain-interface.md)\ - Represents and provides information about an application domain. - + Represents and provides information about an application domain. + [ICorPublishAppDomainEnum Interface](icorpublishappdomainenum-interface.md)\ - Provides methods that traverse a collection of `ICorPublishAppDomain` objects that currently exist within a process. - + Provides methods that traverse a collection of `ICorPublishAppDomain` objects that currently exist within a process. + [ICorPublishEnum Interface](icorpublishenum-interface.md)\ - Serves as the abstract base for publishing enumerators. - + Serves as the abstract base for publishing enumerators. + [ICorPublishProcess Interface](icorpublishprocess-interface.md)\ - Provides methods that access information about a process. - + Provides methods that access information about a process. + [ICorPublishProcessEnum Interface](icorpublishprocessenum-interface.md)\ - Provides methods that traverse a collection of `ICorPublishProcess` objects. + Provides methods that traverse a collection of `ICorPublishProcess` objects. [ISOSDacInterface Interface](isosdacinterface-interface.md)\ Provides helper methods to access data from `SOS`. @@ -451,8 +451,8 @@ This section describes the unmanaged interfaces that handle the debugging of a p [IXCLRDataProcess Interface](ixclrdataprocess-interface.md)\ Provides methods for querying information about a process. - -## Related Sections + +## Related Sections [Debugging Coclasses](debugging-coclasses.md)\ [Debugging Global Static Functions](debugging-global-static-functions.md)\ diff --git a/docs/framework/unmanaged-api/debugging/debugging-structures.md b/docs/framework/unmanaged-api/debugging/debugging-structures.md index da6a0a405f505..52d5c05cfde99 100644 --- a/docs/framework/unmanaged-api/debugging/debugging-structures.md +++ b/docs/framework/unmanaged-api/debugging/debugging-structures.md @@ -33,7 +33,7 @@ This section describes the unmanaged structures that the debugging API uses. Provides information about the layout of an array object in memory. [COR_DEBUG_IL_TO_NATIVE_MAP](cor-debug-il-to-native-map-structure.md) - Contains the offsets that are used to map Microsoft intermediate language (MSIL) code to native code. + Contains the offsets that are used to map common intermediate language (CIL) code to native code. [COR_DEBUG_STEP_RANGE](cor-debug-step-range-structure.md) Contains the offset information for a range of code. diff --git a/docs/framework/unmanaged-api/debugging/icordebugcode-createbreakpoint-method.md b/docs/framework/unmanaged-api/debugging/icordebugcode-createbreakpoint-method.md index 304a9e41ac902..132db3e554f8a 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugcode-createbreakpoint-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugcode-createbreakpoint-method.md @@ -2,54 +2,54 @@ description: "Learn more about: ICorDebugCode::CreateBreakpoint Method" title: "ICorDebugCode::CreateBreakpoint Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugCode.CreateBreakpoint" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugCode::CreateBreakpoint" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugCode::CreateBreakpoint method [.NET Framework debugging]" - "CreateBreakpoint method, ICorDebugCode interface [.NET Framework debugging]" ms.assetid: 46842618-0fe4-480b-871c-82fba82d23d9 -topic_type: +topic_type: - "apiref" --- # ICorDebugCode::CreateBreakpoint Method -Creates a breakpoint in this code segment at the specified offset. - -## Syntax - -```cpp -HRESULT CreateBreakpoint ( - [in] ULONG32 offset, - [out] ICorDebugFunctionBreakpoint **ppBreakpoint -); -``` - -## Parameters - - `offset` - [in] The offset at which to create the breakpoint. - - `ppBreakpoint` - [out] A pointer to the address of an "ICorDebugFunctionBreakpoint" object that represents the breakpoint. - -## Remarks - - Before the breakpoint is active, it must be added to the process object. - - If this code is Microsoft intermediate language (MSIL) code, and there is a just-in-time (JIT)-compiled, native version of the code, the breakpoint will be applied in the JIT-compiled code as well. (The same is true if the code is JIT-compiled later.) - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Creates a breakpoint in this code segment at the specified offset. + +## Syntax + +```cpp +HRESULT CreateBreakpoint ( + [in] ULONG32 offset, + [out] ICorDebugFunctionBreakpoint **ppBreakpoint +); +``` + +## Parameters + + `offset` + [in] The offset at which to create the breakpoint. + + `ppBreakpoint` + [out] A pointer to the address of an "ICorDebugFunctionBreakpoint" object that represents the breakpoint. + +## Remarks + + Before the breakpoint is active, it must be added to the process object. + + If this code is common intermediate language (CIL) code, and there is a just-in-time (JIT)-compiled, native version of the code, the breakpoint will be applied in the JIT-compiled code as well. (The same is true if the code is JIT-compiled later.) + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugcode-getiltonativemapping-method.md b/docs/framework/unmanaged-api/debugging/icordebugcode-getiltonativemapping-method.md index 3925ff60ded3e..0b8f0468a95d0 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugcode-getiltonativemapping-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugcode-getiltonativemapping-method.md @@ -2,63 +2,63 @@ description: "Learn more about: ICorDebugCode::GetILToNativeMapping Method" title: "ICorDebugCode::GetILToNativeMapping Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugCode.GetILToNativeMapping" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugCode::GetILToNativeMapping" -helpviewer_keywords: +helpviewer_keywords: - "GetILToNativeMapping method, ICorDebugCode interface [.NET Framework debugging]" - "ICorDebugCode::GetILToNativeMapping method [.NET Framework debugging]" ms.assetid: a8ecd8c8-9627-4356-9c6f-bd05e24637c0 -topic_type: +topic_type: - "apiref" --- # ICorDebugCode::GetILToNativeMapping Method -Gets an array of "COR_DEBUG_IL_TO_NATIVE_MAP" instances that represent mappings from Microsoft intermediate language (MSIL) offsets to native offsets. - -## Syntax - -```cpp -HRESULT GetILToNativeMapping ( - [in] ULONG32 cMap, - [out] ULONG32 *pcMap, - [out, size_is(cMap), length_is(*pcMap)] - COR_DEBUG_IL_TO_NATIVE_MAP map[] -); -``` - -## Parameters - - `cMap` - [in] The size of the `map` array. - - `pcMap` - [out] A pointer to the actual number of elements returned in the `map` array. - - `map` - [out] An array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures, each of which represents a mapping from an MSIL offset to a native offset. - - There is no ordering to the array of elements returned. - -## Remarks - - The `GetILToNativeMapping` method returns meaningful results only if this "ICorDebugCode" instance represents native code that was just-in-time (JIT) compiled from MSIL code. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +Gets an array of "COR_DEBUG_IL_TO_NATIVE_MAP" instances that represent mappings from common intermediate language (CIL) offsets to native offsets. + +## Syntax + +```cpp +HRESULT GetILToNativeMapping ( + [in] ULONG32 cMap, + [out] ULONG32 *pcMap, + [out, size_is(cMap), length_is(*pcMap)] + COR_DEBUG_IL_TO_NATIVE_MAP map[] +); +``` + +## Parameters + + `cMap` + [in] The size of the `map` array. + + `pcMap` + [out] A pointer to the actual number of elements returned in the `map` array. + + `map` + [out] An array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures, each of which represents a mapping from a CIL offset to a native offset. + + There is no ordering to the array of elements returned. + +## Remarks + + The `GetILToNativeMapping` method returns meaningful results only if this "ICorDebugCode" instance represents native code that was just-in-time (JIT) compiled from CIL code. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [ICorDebugCode Interface](icordebugcode-interface1.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugcode-interface1.md b/docs/framework/unmanaged-api/debugging/icordebugcode-interface1.md index fbb0362e51295..f72fa26975621 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugcode-interface1.md +++ b/docs/framework/unmanaged-api/debugging/icordebugcode-interface1.md @@ -2,55 +2,55 @@ description: "Learn more about: ICorDebugCode Interface" title: "ICorDebugCode Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugCode" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugCode" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugCode interface [.NET Framework debugging]" ms.assetid: 7bd14fb6-8b54-4484-a891-e3c21859c019 -topic_type: +topic_type: - "apiref" --- # ICorDebugCode Interface -Represents a segment of either Microsoft intermediate language (MSIL) code or native code. - -## Methods - -|Method|Description| -|------------|-----------------| -|[CreateBreakpoint Method](icordebugcode-createbreakpoint-method.md)|Creates a breakpoint at the specified offset.| -|[GetAddress Method](icordebugcode-getaddress-method.md)|Gets the relative virtual address (RVA) of the code segment that this `ICorDebugCode` represents.| -|[GetCode Method](icordebugcode-getcode-method.md)|Gets all the code for the specified function, formatted for disassembly. This method has been deprecated; use [ICorDebugCode2::GetCodeChunks](icordebugcode2-getcodechunks-method.md) instead.| -|[GetEnCRemapSequencePoints Method](icordebugcode-getencremapsequencepoints-method.md)|Not implemented.| -|[GetFunction Method](icordebugcode-getfunction-method.md)|Gets the "ICorDebugFunction" associated with this `ICorDebugCode`.| -|[GetILToNativeMapping Method](icordebugcode-getiltonativemapping-method.md)|Gets an array of "COR_DEBUG_IL_TO_NATIVE_MAP" instances that represent mappings from MSIL offsets to native offsets.| -|[GetSize Method](icordebugcode-getsize-method.md)|Gets the size, in bytes, of the binary code represented by this `ICorDebugCode`.| -|[GetVersionNumber Method](icordebugcode-getversionnumber-method.md)|Gets the one-based number that identifies the version of the code that this `ICorDebugCode` represents.| -|[IsIL Method](icordebugcode-isil-method.md)|Gets a value that indicates whether this `ICorDebugCode` is compiled in MSIL.| - -## Remarks - - `ICorDebugCode` can represent either MSIL or native code. An "ICorDebugFunction" object that represents MSIL code can have either zero or one `ICorDebugCode` objects associated with it. An "ICorDebugFunction" object that represents native code can have any number of `ICorDebugCode` objects associated with it. - +Represents a segment of either common intermediate language (CIL) code or native code. + +## Methods + +|Method|Description| +|------------|-----------------| +|[CreateBreakpoint Method](icordebugcode-createbreakpoint-method.md)|Creates a breakpoint at the specified offset.| +|[GetAddress Method](icordebugcode-getaddress-method.md)|Gets the relative virtual address (RVA) of the code segment that this `ICorDebugCode` represents.| +|[GetCode Method](icordebugcode-getcode-method.md)|Gets all the code for the specified function, formatted for disassembly. This method has been deprecated; use [ICorDebugCode2::GetCodeChunks](icordebugcode2-getcodechunks-method.md) instead.| +|[GetEnCRemapSequencePoints Method](icordebugcode-getencremapsequencepoints-method.md)|Not implemented.| +|[GetFunction Method](icordebugcode-getfunction-method.md)|Gets the "ICorDebugFunction" associated with this `ICorDebugCode`.| +|[GetILToNativeMapping Method](icordebugcode-getiltonativemapping-method.md)|Gets an array of "COR_DEBUG_IL_TO_NATIVE_MAP" instances that represent mappings from CIL offsets to native offsets.| +|[GetSize Method](icordebugcode-getsize-method.md)|Gets the size, in bytes, of the binary code represented by this `ICorDebugCode`.| +|[GetVersionNumber Method](icordebugcode-getversionnumber-method.md)|Gets the one-based number that identifies the version of the code that this `ICorDebugCode` represents.| +|[IsIL Method](icordebugcode-isil-method.md)|Gets a value that indicates whether this `ICorDebugCode` is compiled in CIL.| + +## Remarks + + `ICorDebugCode` can represent either CIL or native code. An "ICorDebugFunction" object that represents CIL code can have either zero or one `ICorDebugCode` objects associated with it. An "ICorDebugFunction" object that represents native code can have any number of `ICorDebugCode` objects associated with it. + > [!NOTE] -> This interface does not support being called remotely, either cross-machine or cross-process. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +> This interface does not support being called remotely, either cross-machine or cross-process. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [ICorDebugCode3 Interface](icordebugcode3-interface.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugcode-isil-method.md b/docs/framework/unmanaged-api/debugging/icordebugcode-isil-method.md index fdee38ef19e8d..e80d780c4601a 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugcode-isil-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugcode-isil-method.md @@ -19,7 +19,7 @@ topic_type: --- # ICorDebugCode::IsIL Method -Gets a value that indicates whether this "ICorDebugCode" represents code that was compiled in Microsoft intermediate language (MSIL). +Gets a value that indicates whether this "ICorDebugCode" represents code that was compiled in common intermediate language (CIL). ## Syntax @@ -31,8 +31,8 @@ HRESULT IsIL ( ## Parameters -`pbIL` -[out] `true` if this `ICorDebugCode` represents code that was compiled in MSIL; otherwise, `false`. +`pbIL` +[out] `true` if this `ICorDebugCode` represents code that was compiled in CIL; otherwise, `false`. ## Requirements diff --git a/docs/framework/unmanaged-api/debugging/icordebugcode2-getcodechunks-method.md b/docs/framework/unmanaged-api/debugging/icordebugcode2-getcodechunks-method.md index 7035b85aaf94e..a1ce1abcf4990 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugcode2-getcodechunks-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugcode2-getcodechunks-method.md @@ -34,18 +34,18 @@ HRESULT GetCodeChunks ( ## Parameters -`cbufSize` +`cbufSize` [in] Size of the `chunks` array. -`pcnumChunks` +`pcnumChunks` [out] The number of chunks returned in the `chunks` array. -`chunks` +`chunks` [out] An array of "CodeChunkInfo" structures, each of which represents a single chunk of code. If the value of `cbufSize` is 0, this parameter can be null. ## Remarks -The code chunks will never overlap, and they will follow the order in which they would have been concatenated by [ICorDebugCode::GetCode](icordebugcode-getcode-method.md). A Microsoft intermediate language (MSIL) code object in the .NET Framework version 2.0 will comprise a single code chunk. +The code chunks will never overlap, and they will follow the order in which they would have been concatenated by [ICorDebugCode::GetCode](icordebugcode-getcode-method.md). A common intermediate language (CIL) code object in the .NET Framework version 2.0 will comprise a single code chunk. ## Requirements diff --git a/docs/framework/unmanaged-api/debugging/icordebugfunction-getilcode-method.md b/docs/framework/unmanaged-api/debugging/icordebugfunction-getilcode-method.md index 8d098e5e64bcb..3b914e360a0e7 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugfunction-getilcode-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugfunction-getilcode-method.md @@ -2,48 +2,48 @@ description: "Learn more about: ICorDebugFunction::GetILCode Method" title: "ICorDebugFunction::GetILCode Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugFunction.GetILCode" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugFunction::GetILCode" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugFunction::GetILCode method [.NET Framework debugging]" - "GetILCode method [.NET Framework debugging]" ms.assetid: f794dd47-a7cd-47f6-96e9-a41a4dae8e72 -topic_type: +topic_type: - "apiref" --- # ICorDebugFunction::GetILCode Method -Gets the ICorDebugCode instance that represents the Microsoft intermediate language (MSIL) code associated with this ICorDebugFunction object. - -## Syntax - -```cpp -HRESULT GetILCode ( - [out] ICorDebugCode **ppCode -); -``` - -## Parameters - - `ppCode` - [out] A pointer to the `ICorDebugCode` instance, or null, if the function was not compiled into MSIL. - -## Remarks - - If Edit and Continue has been allowed on this function, the `GetILCode` method will get the MSIL code corresponding to this function's edited version of the code in the common language runtime (CLR). - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Gets the ICorDebugCode instance that represents the common intermediate language (CIL) code associated with this ICorDebugFunction object. + +## Syntax + +```cpp +HRESULT GetILCode ( + [out] ICorDebugCode **ppCode +); +``` + +## Parameters + + `ppCode` + [out] A pointer to the `ICorDebugCode` instance, or null, if the function was not compiled into CIL. + +## Remarks + + If Edit and Continue has been allowed on this function, the `GetILCode` method will get the CIL code corresponding to this function's edited version of the code in the common language runtime (CLR). + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugfunction-getnativecode-method.md b/docs/framework/unmanaged-api/debugging/icordebugfunction-getnativecode-method.md index 3c6d5022a687c..2c7490dcd1c21 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugfunction-getnativecode-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugfunction-getnativecode-method.md @@ -2,48 +2,48 @@ description: "Learn more about: ICorDebugFunction::GetNativeCode Method" title: "ICorDebugFunction::GetNativeCode Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugFunction.GetNativeCode" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugFunction::GetNativeCode" -helpviewer_keywords: +helpviewer_keywords: - "GetNativeCode method [.NET Framework debugging]" - "ICorDebugFunction::GetNativeCode method [.NET Framework debugging]" ms.assetid: c8a34916-0eef-4987-8d29-c8bcb4be9cf6 -topic_type: +topic_type: - "apiref" --- # ICorDebugFunction::GetNativeCode Method -Gets the native code for the function that is represented by this ICorDebugFunction instance. - -## Syntax - -```cpp -HRESULT GetNativeCode ( - [out] ICorDebugCode **ppCode -); -``` - -## Parameters - - `ppCode` - [out] A pointer to the ICorDebugCode instance that represents the native code for this function, or null, if this function is Microsoft intermediate language (MSIL) code that has not been just-in-time (JIT) compiled. - -## Remarks - - If the function that is represented by this `ICorDebugFunction` instance has been JIT-compiled more than once, as in the case of generic types, `GetNativeCode` returns a random native code object. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Gets the native code for the function that is represented by this ICorDebugFunction instance. + +## Syntax + +```cpp +HRESULT GetNativeCode ( + [out] ICorDebugCode **ppCode +); +``` + +## Parameters + + `ppCode` + [out] A pointer to the ICorDebugCode instance that represents the native code for this function, or null, if this function is common intermediate language (CIL) code that has not been just-in-time (JIT) compiled. + +## Remarks + + If the function that is represented by this `ICorDebugFunction` instance has been JIT-compiled more than once, as in the case of generic types, `GetNativeCode` returns a random native code object. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugfunction-interface1.md b/docs/framework/unmanaged-api/debugging/icordebugfunction-interface1.md index e4f59d869a1c8..3cbbdfc8e1d6c 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugfunction-interface1.md +++ b/docs/framework/unmanaged-api/debugging/icordebugfunction-interface1.md @@ -2,60 +2,60 @@ description: "Learn more about: ICorDebugFunction Interface" title: "ICorDebugFunction Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugFunction" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugFunction" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugFunction interface [.NET Framework debugging]" ms.assetid: 783faea9-8083-41c1-b04a-51a81ac4c8f3 -topic_type: +topic_type: - "apiref" --- # ICorDebugFunction Interface -Represents a managed function or method. - -## Methods - -|Method|Description| -|------------|-----------------| -|[CreateBreakpoint Method](icordebugfunction-createbreakpoint-method.md)|Creates a breakpoint at the beginning of this function.| -|[GetClass Method](icordebugfunction-getclass-method.md)|Gets an ICorDebugClass object that represents the class this function is a member of.| -|[GetCurrentVersionNumber Method](icordebugfunction-getcurrentversionnumber-method.md)|Gets the version number of the latest edit made to this function.| -|[GetILCode Method](icordebugfunction-getilcode-method.md)|Gets the Microsoft intermediate language (MSIL) code for this function.| -|[GetLocalVarSigToken Method](icordebugfunction-getlocalvarsigtoken-method.md)|Gets the metadata token for the local variable signature of the function that is represented by this `ICorDebugFunction` instance.| -|[GetModule Method](icordebugfunction-getmodule-method.md)|Gets the module in which this function is defined.| -|[GetNativeCode Method](icordebugfunction-getnativecode-method.md)|Gets the native code for this function.| -|[GetToken Method](icordebugfunction-gettoken-method.md)|Gets the metadata token for this function.| - -## Remarks - - The `ICorDebugFunction` interface does not represent a function with generic type parameters. For example, an `ICorDebugFunction` instance would represent `Func` but not `Func`. Call [ICorDebugILFrame2::EnumerateTypeParameters](icordebugilframe2-enumeratetypeparameters-method.md) to get the generic type parameters. - - The relationship between a method's metadata token, `mdMethodDef`, and a method's `ICorDebugFunction` object is dependent upon whether Edit and Continue is allowed on the function: - -- If Edit and Continue is not allowed on the function, a one-to-one relationship exists between the `ICorDebugFunction` object and the `mdMethodDef` token. That is, the function has one `ICorDebugFunction` object and one `mdMethodDef` token. - -- If Edit and Continue is allowed on the function, a many-to-one relationship exists between the `ICorDebugFunction` object and the `mdMethodDef` token. That is, the function may have many instances of `ICorDebugFunction`, one for each version of the function, but only one `mdMethodDef` token. - +Represents a managed function or method. + +## Methods + +|Method|Description| +|------------|-----------------| +|[CreateBreakpoint Method](icordebugfunction-createbreakpoint-method.md)|Creates a breakpoint at the beginning of this function.| +|[GetClass Method](icordebugfunction-getclass-method.md)|Gets an ICorDebugClass object that represents the class this function is a member of.| +|[GetCurrentVersionNumber Method](icordebugfunction-getcurrentversionnumber-method.md)|Gets the version number of the latest edit made to this function.| +|[GetILCode Method](icordebugfunction-getilcode-method.md)|Gets the common intermediate language (CIL) code for this function.| +|[GetLocalVarSigToken Method](icordebugfunction-getlocalvarsigtoken-method.md)|Gets the metadata token for the local variable signature of the function that is represented by this `ICorDebugFunction` instance.| +|[GetModule Method](icordebugfunction-getmodule-method.md)|Gets the module in which this function is defined.| +|[GetNativeCode Method](icordebugfunction-getnativecode-method.md)|Gets the native code for this function.| +|[GetToken Method](icordebugfunction-gettoken-method.md)|Gets the metadata token for this function.| + +## Remarks + + The `ICorDebugFunction` interface does not represent a function with generic type parameters. For example, an `ICorDebugFunction` instance would represent `Func` but not `Func`. Call [ICorDebugILFrame2::EnumerateTypeParameters](icordebugilframe2-enumeratetypeparameters-method.md) to get the generic type parameters. + + The relationship between a method's metadata token, `mdMethodDef`, and a method's `ICorDebugFunction` object is dependent upon whether Edit and Continue is allowed on the function: + +- If Edit and Continue is not allowed on the function, a one-to-one relationship exists between the `ICorDebugFunction` object and the `mdMethodDef` token. That is, the function has one `ICorDebugFunction` object and one `mdMethodDef` token. + +- If Edit and Continue is allowed on the function, a many-to-one relationship exists between the `ICorDebugFunction` object and the `mdMethodDef` token. That is, the function may have many instances of `ICorDebugFunction`, one for each version of the function, but only one `mdMethodDef` token. + > [!NOTE] -> This interface does not support being called remotely, either cross-machine or cross-process. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +> This interface does not support being called remotely, either cross-machine or cross-process. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [Debugging Interfaces](debugging-interfaces.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe-cansetip-method.md b/docs/framework/unmanaged-api/debugging/icordebugilframe-cansetip-method.md index 355e3292e7af9..7a18dd1768c28 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe-cansetip-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe-cansetip-method.md @@ -2,48 +2,48 @@ description: "Learn more about: ICorDebugILFrame::CanSetIP Method" title: "ICorDebugILFrame::CanSetIP Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame.CanSetIP" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame::CanSetIP" -helpviewer_keywords: +helpviewer_keywords: - "CanSetIP method, ICorDebugILFrame interface [.NET Framework debugging]" - "ICorDebugILFrame::CanSetIP method [.NET Framework debugging]" ms.assetid: 16caf02f-c71e-486c-90b0-f0e54357d8f0 -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame::CanSetIP Method -Gets an HRESULT that indicates whether it is safe to set the instruction pointer to the specified offset location in Microsoft Intermediate Language (MSIL) code. - -## Syntax - -```cpp -HRESULT CanSetIP ( - [in] ULONG32 nOffset -); -``` - -## Parameters - - `nOffset` - [in] The desired setting for the instruction pointer. - -## Remarks - - Use the `CanSetIP` method before calling the [ICorDebugILFrame::SetIP](icordebugilframe-setip-method.md) method. If `CanSetIP` returns any HRESULT other than S_OK, you can still invoke `ICorDebugILFrame::SetIP`, but there is no guarantee that the debugger will continue the safe and correct execution of the code being debugged. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug,h - - **Library:** CorGuids.lib - +Gets an HRESULT that indicates whether it is safe to set the instruction pointer to the specified offset location in common intermediate language (CIL) code. + +## Syntax + +```cpp +HRESULT CanSetIP ( + [in] ULONG32 nOffset +); +``` + +## Parameters + + `nOffset` + [in] The desired setting for the instruction pointer. + +## Remarks + + Use the `CanSetIP` method before calling the [ICorDebugILFrame::SetIP](icordebugilframe-setip-method.md) method. If `CanSetIP` returns any HRESULT other than S_OK, you can still invoke `ICorDebugILFrame::SetIP`, but there is no guarantee that the debugger will continue the safe and correct execution of the code being debugged. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug,h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe-getargument-method.md b/docs/framework/unmanaged-api/debugging/icordebugilframe-getargument-method.md index 231d21d91f8b5..0eb22accd3e54 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe-getargument-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe-getargument-method.md @@ -2,52 +2,52 @@ description: "Learn more about: ICorDebugILFrame::GetArgument Method" title: "ICorDebugILFrame::GetArgument Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame.GetArgument" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame::GetArgument" -helpviewer_keywords: +helpviewer_keywords: - "GetArgument method [.NET Framework debugging]" - "ICorDebugILFrame::GetArgument method [.NET Framework debugging]" ms.assetid: 4e2fd423-f643-4c27-ba5f-41b5ebc3b416 -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame::GetArgument Method -Gets the value of the specified argument in this Microsoft intermediate language (MSIL) stack frame. - -## Syntax - -```cpp -HRESULT GetArgument ( - [in] DWORD dwIndex, - [out] ICorDebugValue **ppValue -); -``` - -## Parameters - - `dwIndex` - [in] The index of the argument in this MSIL stack frame. - - `ppValue` - [out] A pointer to the address of an ICorDebugValue object that represents the retrieved value. - -## Remarks - - The `GetArgument` method can be used either in an MSIL stack frame or in a just-in-time (JIT) compiled frame. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Gets the value of the specified argument in this common intermediate language (CIL) stack frame. + +## Syntax + +```cpp +HRESULT GetArgument ( + [in] DWORD dwIndex, + [out] ICorDebugValue **ppValue +); +``` + +## Parameters + + `dwIndex` + [in] The index of the argument in this CIL stack frame. + + `ppValue` + [out] A pointer to the address of an ICorDebugValue object that represents the retrieved value. + +## Remarks + + The `GetArgument` method can be used either in an CIL stack frame or in a just-in-time (JIT) compiled frame. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe-getip-method.md b/docs/framework/unmanaged-api/debugging/icordebugilframe-getip-method.md index 2ec51e2306579..af89059646cfa 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe-getip-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe-getip-method.md @@ -2,54 +2,54 @@ description: "Learn more about: ICorDebugILFrame::GetIP Method" title: "ICorDebugILFrame::GetIP Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame.GetIP" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame::GetIP" -helpviewer_keywords: +helpviewer_keywords: - "GetIP method, ICorDebugILFrame interface [.NET Framework debugging]" - "ICorDebugILFrame::GetIP method [.NET Framework debugging]" ms.assetid: 18217ba1-1776-4297-a3b9-f77e64b0fead -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame::GetIP Method -Gets the value of the instruction pointer and a bitwise combination value that describes how the value of the instruction pointer was obtained. - -## Syntax - -```cpp -HRESULT GetIP ( +Gets the value of the instruction pointer and a bitwise combination value that describes how the value of the instruction pointer was obtained. + +## Syntax + +```cpp +HRESULT GetIP ( [out] ULONG32 *pnOffset, - [out] CorDebugMappingResult *pMappingResult -); -``` - -## Parameters - - `pnOffset` - [out] The value of the instruction pointer. - - `pMappingResult` - [out] A pointer to a bitwise combination of the CorDebugMappingResult enumeration values that describe how the value of the instruction pointer was obtained. - -## Remarks - - The value of the instruction pointer is the stack frame's offset into the function's Microsoft intermediate language (MSIL) code. If the stack frame is active, this address is the next instruction to execute. If the stack frame is not active, this address is the next instruction to execute when the stack frame is reactivated. - - If this frame is a just-in-time (JIT) compiled frame, the value of the instruction pointer will be determined by mapping backwards from the actual native instruction pointer, so the value may be only approximate. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - + [out] CorDebugMappingResult *pMappingResult +); +``` + +## Parameters + + `pnOffset` + [out] The value of the instruction pointer. + + `pMappingResult` + [out] A pointer to a bitwise combination of the CorDebugMappingResult enumeration values that describe how the value of the instruction pointer was obtained. + +## Remarks + + The value of the instruction pointer is the stack frame's offset into the function's common intermediate language (CIL) code. If the stack frame is active, this address is the next instruction to execute. If the stack frame is not active, this address is the next instruction to execute when the stack frame is reactivated. + + If this frame is a just-in-time (JIT) compiled frame, the value of the instruction pointer will be determined by mapping backwards from the actual native instruction pointer, so the value may be only approximate. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe-getlocalvariable-method.md b/docs/framework/unmanaged-api/debugging/icordebugilframe-getlocalvariable-method.md index 7798a00d5ddb8..dd583d620abdd 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe-getlocalvariable-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe-getlocalvariable-method.md @@ -2,52 +2,52 @@ description: "Learn more about: ICorDebugILFrame::GetLocalVariable Method" title: "ICorDebugILFrame::GetLocalVariable Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame.GetLocalVariable" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame::GetLocalVariable" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugILFrame::GetLocalVariable method [.NET Framework debugging]" - "GetLocalVariable method [.NET Framework debugging]" ms.assetid: c8706356-d50b-4f87-a40c-39c3b7f4fd38 -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame::GetLocalVariable Method -Gets the value of the specified local variable in this Microsoft intermediate language (MSIL) stack frame. - -## Syntax - -```cpp -HRESULT GetLocalVariable ( - [in] DWORD dwIndex, - [out] ICorDebugValue **ppValue -); -``` - -## Parameters - - `dwIndex` - [in] The index of the local variable in this MSIL stack frame. - - `ppValue` - [out] A pointer to the address of an ICorDebugValue object that represents the retrieved value. - -## Remarks - - The `GetLocalVariable` method can be used either in an MSIL stack frame or in a just-in-time (JIT) compiled frame. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Gets the value of the specified local variable in this common intermediate language (CIL) stack frame. + +## Syntax + +```cpp +HRESULT GetLocalVariable ( + [in] DWORD dwIndex, + [out] ICorDebugValue **ppValue +); +``` + +## Parameters + + `dwIndex` + [in] The index of the local variable in this CIL stack frame. + + `ppValue` + [out] A pointer to the address of an ICorDebugValue object that represents the retrieved value. + +## Remarks + + The `GetLocalVariable` method can be used either in an CIL stack frame or in a just-in-time (JIT) compiled frame. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe-interface.md b/docs/framework/unmanaged-api/debugging/icordebugilframe-interface.md index c49ca069afc8f..b7aaa69d24338 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe-interface.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe-interface.md @@ -2,55 +2,55 @@ description: "Learn more about: ICorDebugILFrame Interface" title: "ICorDebugILFrame Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugILFrame interface [.NET Framework debugging]" ms.assetid: d5cf5056-da4d-4629-914d-afe42a5393df -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame Interface -Represents a stack frame of Microsoft intermediate language (MSIL) code. This interface is a subclass of the ICorDebugFrame interface. - -## Methods - -|Method|Description| -|------------|-----------------| -|[CanSetIP Method](icordebugilframe-cansetip-method.md)|Gets a value that indicates whether it is safe to set the instruction pointer to the specified offset location.| -|[EnumerateArguments Method](icordebugilframe-enumeratearguments-method.md)|Gets an enumerator for the arguments in this frame.| -|[EnumerateLocalVariables Method](icordebugilframe-enumeratelocalvariables-method.md)|Gets an enumerator for the local variables in this frame.| -|[GetArgument Method](icordebugilframe-getargument-method.md)|Gets the value of the specified argument in this MSIL stack frame.| -|[GetIP Method](icordebugilframe-getip-method.md)|Gets the value of the instruction pointer and a bitwise combination value that describes how the value of the instruction pointer was obtained.| -|[GetLocalVariable Method](icordebugilframe-getlocalvariable-method.md)|Gets the value of the specified local variable in this MSIL stack frame.| -|[GetStackDepth Method](icordebugilframe-getstackdepth-method.md)|Not implemented.| -|[GetStackValue Method](icordebugilframe-getstackvalue-method.md)|Not implemented.| -|[SetIP Method](icordebugilframe-setip-method.md)|Sets the instruction pointer to the specified offset location in the MSIL code.| - -## Remarks - - The `ICorDebugILFrame` interface is a specialized ICorDebugFrame interface. It is used either for MSIL code frames or for just-in-time (JIT) compiled frames. The JIT-compiled frames implement both the `ICorDebugILFrame` interface and the ICorDebugNativeFrame interface. - +Represents a stack frame of common intermediate language (CIL) code. This interface is a subclass of the ICorDebugFrame interface. + +## Methods + +|Method|Description| +|------------|-----------------| +|[CanSetIP Method](icordebugilframe-cansetip-method.md)|Gets a value that indicates whether it is safe to set the instruction pointer to the specified offset location.| +|[EnumerateArguments Method](icordebugilframe-enumeratearguments-method.md)|Gets an enumerator for the arguments in this frame.| +|[EnumerateLocalVariables Method](icordebugilframe-enumeratelocalvariables-method.md)|Gets an enumerator for the local variables in this frame.| +|[GetArgument Method](icordebugilframe-getargument-method.md)|Gets the value of the specified argument in this CIL stack frame.| +|[GetIP Method](icordebugilframe-getip-method.md)|Gets the value of the instruction pointer and a bitwise combination value that describes how the value of the instruction pointer was obtained.| +|[GetLocalVariable Method](icordebugilframe-getlocalvariable-method.md)|Gets the value of the specified local variable in this CIL stack frame.| +|[GetStackDepth Method](icordebugilframe-getstackdepth-method.md)|Not implemented.| +|[GetStackValue Method](icordebugilframe-getstackvalue-method.md)|Not implemented.| +|[SetIP Method](icordebugilframe-setip-method.md)|Sets the instruction pointer to the specified offset location in the CIL code.| + +## Remarks + + The `ICorDebugILFrame` interface is a specialized ICorDebugFrame interface. It is used either for CIL code frames or for just-in-time (JIT) compiled frames. The JIT-compiled frames implement both the `ICorDebugILFrame` interface and the ICorDebugNativeFrame interface. + > [!NOTE] -> This interface does not support being called remotely, either cross-machine or cross-process. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +> This interface does not support being called remotely, either cross-machine or cross-process. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [Debugging Interfaces](debugging-interfaces.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe-setip-method.md b/docs/framework/unmanaged-api/debugging/icordebugilframe-setip-method.md index 76924f05ee023..8d570e0e8b6eb 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe-setip-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe-setip-method.md @@ -2,52 +2,52 @@ description: "Learn more about: ICorDebugILFrame::SetIP Method" title: "ICorDebugILFrame::SetIP Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame.SetIP" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame::SetIP" -helpviewer_keywords: +helpviewer_keywords: - "SetIP method, ICorDebugILFrame interface [.NET Framework debugging]" - "ICorDebugILFrame::SetIP method [.NET Framework debugging]" ms.assetid: 23f38dc1-85e4-4263-9235-2d05bbb6a833 -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame::SetIP Method -Sets the instruction pointer to the specified offset location in the Microsoft intermediate language (MSIL) code. - -## Syntax - -```cpp -HRESULT SetIP ( - [in] ULONG32 nOffset -); -``` - -## Parameters - - `nOffset` - The offset location in the MSIL code. - -## Remarks - - Calls to `SetIP` immediately invalidate all frames and chains for the current thread. If the debugger needs frame information after a call to `SetIP`, it must perform a new stack trace. - - [ICorDebug](icordebug-interface.md) will attempt to keep the stack frame in a valid state. However, even if the frame is in a valid state, there still may be problems such as uninitialized local variables. The caller is responsible for ensuring the coherency of the running program. - - On 64-bit platforms, the instruction pointer cannot be moved out of a `catch` or `finally` block. If `SetIP` is called to make such a move on a 64-bit platform, it will return an HRESULT indicating failure. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Sets the instruction pointer to the specified offset location in the common intermediate language (CIL) code. + +## Syntax + +```cpp +HRESULT SetIP ( + [in] ULONG32 nOffset +); +``` + +## Parameters + + `nOffset` + The offset location in the CIL code. + +## Remarks + + Calls to `SetIP` immediately invalidate all frames and chains for the current thread. If the debugger needs frame information after a call to `SetIP`, it must perform a new stack trace. + + [ICorDebug](icordebug-interface.md) will attempt to keep the stack frame in a valid state. However, even if the frame is in a valid state, there still may be problems such as uninitialized local variables. The caller is responsible for ensuring the coherency of the running program. + + On 64-bit platforms, the instruction pointer cannot be moved out of a `catch` or `finally` block. If `SetIP` is called to make such a move on a 64-bit platform, it will return an HRESULT indicating failure. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe2-interface.md b/docs/framework/unmanaged-api/debugging/icordebugilframe2-interface.md index 55eec602ff0dd..a60901785989e 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe2-interface.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe2-interface.md @@ -2,46 +2,46 @@ description: "Learn more about: ICorDebugILFrame2 Interface" title: "ICorDebugILFrame2 Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame2" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame2" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugILFrame2 interface [.NET Framework debugging]" ms.assetid: f94b9d53-d8f8-4424-a95e-53a1bfd26e4a -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame2 Interface -A logical extension of the ICorDebugILFrame interface. - -## Methods - -|Method|Description| -|------------|-----------------| -|[EnumerateTypeParameters Method](icordebugilframe2-enumeratetypeparameters-method.md)|Gets an ICorDebugTypeEnum object that contains the parameters in this frame.| -|[RemapFunction Method](icordebugilframe2-remapfunction-method.md)|Remaps an edited function by specifying the new MSIL offset.| - -## Remarks - +A logical extension of the ICorDebugILFrame interface. + +## Methods + +|Method|Description| +|------------|-----------------| +|[EnumerateTypeParameters Method](icordebugilframe2-enumeratetypeparameters-method.md)|Gets an ICorDebugTypeEnum object that contains the parameters in this frame.| +|[RemapFunction Method](icordebugilframe2-remapfunction-method.md)|Remaps an edited function by specifying the new CIL offset.| + +## Remarks + > [!NOTE] -> This interface does not support being called remotely, either cross-machine or cross-process. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +> This interface does not support being called remotely, either cross-machine or cross-process. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [Debugging Interfaces](debugging-interfaces.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe2-remapfunction-method.md b/docs/framework/unmanaged-api/debugging/icordebugilframe2-remapfunction-method.md index 7949a3096b15c..44fa2e99b611c 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe2-remapfunction-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe2-remapfunction-method.md @@ -2,59 +2,59 @@ description: "Learn more about: ICorDebugILFrame2::RemapFunction Method" title: "ICorDebugILFrame2::RemapFunction Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame2.RemapFunction" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame2::RemapFunction" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugILFrame2::RemapFunction method [.NET Framework debugging]" - "RemapFunction method [.NET Framework debugging]" ms.assetid: dd639ba0-f77b-426d-9ff6-f92706840348 -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame2::RemapFunction Method -Remaps an edited function by specifying the new Microsoft intermediate language (MSIL) offset - -## Syntax - -```cpp -HRESULT RemapFunction ( - [in] ULONG32 newILOffset -); -``` - -## Parameters - - `newILOffset` - [in] The stack frame's new MSIL offset at which the instruction pointer should be placed. This value must be a sequence point. - - It is the caller’s responsibility to ensure the validity of this value. For example, the MSIL offset is not valid if it is outside the bounds of the function. - -## Remarks - - When a frame’s function has been edited, the debugger can call the `RemapFunction` method to swap in the latest version of the frame's function so it can be executed. The code execution will begin at the given MSIL offset. - +Remaps an edited function by specifying the new common intermediate language (CIL) offset + +## Syntax + +```cpp +HRESULT RemapFunction ( + [in] ULONG32 newILOffset +); +``` + +## Parameters + + `newILOffset` + [in] The stack frame's new CIL offset at which the instruction pointer should be placed. This value must be a sequence point. + + It is the caller’s responsibility to ensure the validity of this value. For example, the CIL offset is not valid if it is outside the bounds of the function. + +## Remarks + + When a frame’s function has been edited, the debugger can call the `RemapFunction` method to swap in the latest version of the frame's function so it can be executed. The code execution will begin at the given CIL offset. + > [!NOTE] -> Calling `RemapFunction`, like calling [ICorDebugILFrame::SetIP](icordebugilframe-setip-method.md), will immediately invalidate all debugging interfaces that are related to generating a stack trace for the thread. These interfaces include [ICorDebugChain](icordebugchain-interface.md), ICorDebugILFrame, ICorDebugInternalFrame, and ICorDebugNativeFrame. - - The `RemapFunction` method can be called only in the context of the current frame, and only in one of the following cases: - -- After receipt of a [ICorDebugManagedCallback2::FunctionRemapOpportunity](icordebugmanagedcallback2-functionremapopportunity-method.md) callback that has not yet been continued. - -- While code execution is stopped because of an [ICorDebugManagedCallback::EditAndContinueRemap](icordebugmanagedcallback-editandcontinueremap-method.md) event for this frame. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +> Calling `RemapFunction`, like calling [ICorDebugILFrame::SetIP](icordebugilframe-setip-method.md), will immediately invalidate all debugging interfaces that are related to generating a stack trace for the thread. These interfaces include [ICorDebugChain](icordebugchain-interface.md), ICorDebugILFrame, ICorDebugInternalFrame, and ICorDebugNativeFrame. + + The `RemapFunction` method can be called only in the context of the current frame, and only in one of the following cases: + +- After receipt of a [ICorDebugManagedCallback2::FunctionRemapOpportunity](icordebugmanagedcallback2-functionremapopportunity-method.md) callback that has not yet been continued. + +- While code execution is stopped because of an [ICorDebugManagedCallback::EditAndContinueRemap](icordebugmanagedcallback-editandcontinueremap-method.md) event for this frame. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-exception-method.md b/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-exception-method.md index f4d59f1bbc544..d7ecf3c258070 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-exception-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-exception-method.md @@ -2,83 +2,83 @@ description: "Learn more about: ICorDebugManagedCallback2::Exception Method" title: "ICorDebugManagedCallback2::Exception Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugManagedCallback2.Exception" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugManagedCallback2::Exception" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugManagedCallback2::Exception method [.NET Framework debugging]" - "Exception method, ICorDebugManagedCallback2 interface [.NET Framework debugging]" ms.assetid: 78b0f14f-2fae-4e63-8412-4df119ee8468 -topic_type: +topic_type: - "apiref" --- # ICorDebugManagedCallback2::Exception Method -Notifies the debugger that a search for an exception handler has started. - -## Syntax - -```cpp -HRESULT Exception ( - [in] ICorDebugAppDomain *pAppDomain, - [in] ICorDebugThread *pThread, - [in] ICorDebugFrame *pFrame, - [in] ULONG32 nOffset, - [in] CorDebugExceptionCallbackType dwEventType, - [in] DWORD dwFlags -); -``` - -## Parameters - - `pAppDomain` - [in] A pointer to an ICorDebugAppDomain object that represents the application domain containing the thread on which the exception was thrown. - - `pThread` - [in] A pointer to an ICorDebugThread object that represents the thread on which the exception was thrown. - - `pFrame` - [in] A pointer to an ICorDebugFrame object that represents a frame, as determined by the `dwEventType` parameter. For more information, see the table in the Remarks section. - - `nOffset` - [in] An integer that specifies an offset, as determined by the `dwEventType` parameter. For more information, see the table in the Remarks section. - - `dwEventType` - [in] A value of the CorDebugExceptionCallbackType enumeration that specifies the type of this exception callback. - - `dwFlags` - [in] A value of the [CorDebugExceptionFlags](cordebugexceptionflags-enumeration.md) enumeration that specifies additional information about the exception - -## Remarks - - The `Exception` callback is called at various points during the search phase of the exception-handling process. That is, it can be called more than once while unwinding an exception. - - The exception being processed can be retrieved from the ICorDebugThread object referenced by the `pThread` parameter. - - The particular frame and offset are determined by the `dwEventType` parameter as follows: - -|Value of `dwEventType`|Value of `pFrame`|Value of `nOffset`| -|----------------------------|-----------------------|------------------------| -|DEBUG_EXCEPTION_FIRST_CHANCE|The frame that threw the exception.|The instruction pointer in the frame.| -|DEBUG_EXCEPTION_USER_FIRST_CHANCE|The user-code frame closest to the point of the thrown exception.|The instruction pointer in the frame.| -|DEBUG_EXCEPTION_CATCH_HANDLER_FOUND|The frame that contains the catch handler.|The Microsoft intermediate language (MSIL) offset of the beginning of the catch handler.| -|DEBUG_EXCEPTION_UNHANDLED|NULL|Undefined.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Notifies the debugger that a search for an exception handler has started. + +## Syntax + +```cpp +HRESULT Exception ( + [in] ICorDebugAppDomain *pAppDomain, + [in] ICorDebugThread *pThread, + [in] ICorDebugFrame *pFrame, + [in] ULONG32 nOffset, + [in] CorDebugExceptionCallbackType dwEventType, + [in] DWORD dwFlags +); +``` + +## Parameters + + `pAppDomain` + [in] A pointer to an ICorDebugAppDomain object that represents the application domain containing the thread on which the exception was thrown. + + `pThread` + [in] A pointer to an ICorDebugThread object that represents the thread on which the exception was thrown. + + `pFrame` + [in] A pointer to an ICorDebugFrame object that represents a frame, as determined by the `dwEventType` parameter. For more information, see the table in the Remarks section. + + `nOffset` + [in] An integer that specifies an offset, as determined by the `dwEventType` parameter. For more information, see the table in the Remarks section. + + `dwEventType` + [in] A value of the CorDebugExceptionCallbackType enumeration that specifies the type of this exception callback. + + `dwFlags` + [in] A value of the [CorDebugExceptionFlags](cordebugexceptionflags-enumeration.md) enumeration that specifies additional information about the exception + +## Remarks + + The `Exception` callback is called at various points during the search phase of the exception-handling process. That is, it can be called more than once while unwinding an exception. + + The exception being processed can be retrieved from the ICorDebugThread object referenced by the `pThread` parameter. + + The particular frame and offset are determined by the `dwEventType` parameter as follows: + +|Value of `dwEventType`|Value of `pFrame`|Value of `nOffset`| +|----------------------------|-----------------------|------------------------| +|DEBUG_EXCEPTION_FIRST_CHANCE|The frame that threw the exception.|The instruction pointer in the frame.| +|DEBUG_EXCEPTION_USER_FIRST_CHANCE|The user-code frame closest to the point of the thrown exception.|The instruction pointer in the frame.| +|DEBUG_EXCEPTION_CATCH_HANDLER_FOUND|The frame that contains the catch handler.|The common intermediate language (CIL) offset of the beginning of the catch handler.| +|DEBUG_EXCEPTION_UNHANDLED|NULL|Undefined.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorDebugManagedCallback2 Interface](icordebugmanagedcallback2-interface.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-functionremapopportunity-method.md b/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-functionremapopportunity-method.md index 1df543530af88..642fa363c548b 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-functionremapopportunity-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-functionremapopportunity-method.md @@ -2,70 +2,70 @@ description: "Learn more about: ICorDebugManagedCallback2::FunctionRemapOpportunity Method" title: "ICorDebugManagedCallback2::FunctionRemapOpportunity Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugManagedCallback2.FunctionRemapOpportunity" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugManagedCallback2::FunctionRemapOpportunity" -helpviewer_keywords: +helpviewer_keywords: - "FunctionRemapOpportunity method [.NET Framework debugging]" - "ICorDebugManagedCallback2::FunctionRemapOpportunity method [.NET Framework debugging]" ms.assetid: 0d6471bc-ad9b-4b1d-a307-c10443918863 -topic_type: +topic_type: - "apiref" --- # ICorDebugManagedCallback2::FunctionRemapOpportunity Method -Notifies the debugger that code execution has reached a sequence point in an older version of an edited function. - -## Syntax - -```cpp -HRESULT FunctionRemapOpportunity ( - [in] ICorDebugAppDomain *pAppDomain, - [in] ICorDebugThread *pThread, - [in] ICorDebugFunction *pOldFunction, - [in] ICorDebugFunction *pNewFunction, - [in] ULONG32 oldILOffset -); -``` - -## Parameters - - `pAppDomain` - [in] A pointer to an ICorDebugAppDomain object that represents the application domain containing the edited function. - - `pThread` - [in] A pointer to an ICorDebugThread object that represents the thread on which the remap breakpoint was encountered. - - `pOldFunction` - [in] A pointer to an ICorDebugFunction object that represents the version of the function that is currently running on the thread. - - `pNewFunction` - [in] A pointer to an ICorDebugFunction object that represents the latest version of the function. - - `oldILOffset` - [in] The Microsoft intermediate language (MSIL) offset of the instruction pointer in the old version of the function. - -## Remarks - - This callback gives the debugger an opportunity to remap the instruction pointer to its proper place in the new version of the specified function by calling the [ICorDebugILFrame2::RemapFunction](icordebugilframe2-remapfunction-method.md) method. If the debugger does not call `RemapFunction` before calling the [ICorDebugController::Continue](icordebugcontroller-continue-method.md) method, the runtime will continue to execute the old code and will fire another `FunctionRemapOpportunity` callback at the next sequence point. - - This callback will be invoked for every frame that is executing an older version of the given function until the debugger returns S_OK. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Notifies the debugger that code execution has reached a sequence point in an older version of an edited function. + +## Syntax + +```cpp +HRESULT FunctionRemapOpportunity ( + [in] ICorDebugAppDomain *pAppDomain, + [in] ICorDebugThread *pThread, + [in] ICorDebugFunction *pOldFunction, + [in] ICorDebugFunction *pNewFunction, + [in] ULONG32 oldILOffset +); +``` + +## Parameters + + `pAppDomain` + [in] A pointer to an ICorDebugAppDomain object that represents the application domain containing the edited function. + + `pThread` + [in] A pointer to an ICorDebugThread object that represents the thread on which the remap breakpoint was encountered. + + `pOldFunction` + [in] A pointer to an ICorDebugFunction object that represents the version of the function that is currently running on the thread. + + `pNewFunction` + [in] A pointer to an ICorDebugFunction object that represents the latest version of the function. + + `oldILOffset` + [in] The common intermediate language (CIL) offset of the instruction pointer in the old version of the function. + +## Remarks + + This callback gives the debugger an opportunity to remap the instruction pointer to its proper place in the new version of the specified function by calling the [ICorDebugILFrame2::RemapFunction](icordebugilframe2-remapfunction-method.md) method. If the debugger does not call `RemapFunction` before calling the [ICorDebugController::Continue](icordebugcontroller-continue-method.md) method, the runtime will continue to execute the old code and will fire another `FunctionRemapOpportunity` callback at the next sequence point. + + This callback will be invoked for every frame that is executing an older version of the given function until the debugger returns S_OK. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorDebugManagedCallback2 Interface](icordebugmanagedcallback2-interface.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugmodule-enablejitdebugging-method.md b/docs/framework/unmanaged-api/debugging/icordebugmodule-enablejitdebugging-method.md index bbdbc7b522f88..372d1a0bbad23 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmodule-enablejitdebugging-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmodule-enablejitdebugging-method.md @@ -2,52 +2,52 @@ description: "Learn more about: ICorDebugModule::EnableJITDebugging Method" title: "ICorDebugModule::EnableJITDebugging Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugModule.EnableJITDebugging" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugModule::EnableJITDebugging" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugModule::EnableJITDebugging method [.NET Framework debugging]" - "EnableJITDebugging method [.NET Framework debugging]" ms.assetid: 0a65e2a4-5bb6-496c-ae6f-40474426b5a6 -topic_type: +topic_type: - "apiref" --- # ICorDebugModule::EnableJITDebugging Method -Controls whether the just-in-time (JIT) compiler preserves debugging information for methods within this module. - -## Syntax - -```cpp -HRESULT EnableJITDebugging( - [in] BOOL bTrackJITInfo, - [in] BOOL bAllowJitOpts -); -``` - -## Parameters - - `bTrackJITInfo` - [in] Set this value to `true` to enable the JIT compiler to preserve mapping information between the Microsoft intermediate language (MSIL) version and the JIT-compiled version of each method in this module. - - `bAllowJitOpts` - [in] Set this value to `true` to enable the JIT compiler to generate code with certain JIT-specific optimizations for debugging. - -## Remarks - - JIT debugging is enabled by default for all modules that are loaded when the debugger is active. Programmatically enabling or disabling the settings overrides global settings. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Controls whether the just-in-time (JIT) compiler preserves debugging information for methods within this module. + +## Syntax + +```cpp +HRESULT EnableJITDebugging( + [in] BOOL bTrackJITInfo, + [in] BOOL bAllowJitOpts +); +``` + +## Parameters + + `bTrackJITInfo` + [in] Set this value to `true` to enable the JIT compiler to preserve mapping information between the common intermediate language (CIL) version and the JIT-compiled version of each method in this module. + + `bAllowJitOpts` + [in] Set this value to `true` to enable the JIT compiler to generate code with certain JIT-specific optimizations for debugging. + +## Remarks + + JIT debugging is enabled by default for all modules that are loaded when the debugger is active. Programmatically enabling or disabling the settings overrides global settings. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugmodule-getfunctionfromtoken-method.md b/docs/framework/unmanaged-api/debugging/icordebugmodule-getfunctionfromtoken-method.md index 4d15be5d3f590..4a4cbc1bb269a 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmodule-getfunctionfromtoken-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmodule-getfunctionfromtoken-method.md @@ -2,52 +2,52 @@ description: "Learn more about: ICorDebugModule::GetFunctionFromToken Method" title: "ICorDebugModule::GetFunctionFromToken Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugModule.GetFunctionFromToken" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugModule::GetFunctionFromToken" -helpviewer_keywords: +helpviewer_keywords: - "GetFunctionFromToken method, ICorDebugModule interface [.NET Framework debugging]" - "ICorDebugModule::GetFunctionFromToken method [.NET Framework debugging]" ms.assetid: 6fe12194-4ef7-43c1-9570-ade35ccf127a -topic_type: +topic_type: - "apiref" --- # ICorDebugModule::GetFunctionFromToken Method -Gets the function that is specified by the metadata token. - -## Syntax - -```cpp -HRESULT GetFunctionFromToken( - [in] mdMethodDef methodDef, - [out] ICorDebugFunction **ppFunction -); -``` - -## Parameters - - `methodDef` - [in] A `mdMethodDef` metadata token that references the function's metadata. - - `ppFunction` - [out] A pointer to the address of a ICorDebugFunction interface object that represents the function. - -## Remarks - - The `GetFunctionFromToken` method returns a CORDBG_E_FUNCTION_NOT_IL HRESULT if the value passed in `methodDef` does not refer to a Microsoft intermediate language (MSIL) method. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Gets the function that is specified by the metadata token. + +## Syntax + +```cpp +HRESULT GetFunctionFromToken( + [in] mdMethodDef methodDef, + [out] ICorDebugFunction **ppFunction +); +``` + +## Parameters + + `methodDef` + [in] A `mdMethodDef` metadata token that references the function's metadata. + + `ppFunction` + [out] A pointer to the address of a ICorDebugFunction interface object that represents the function. + +## Remarks + + The `GetFunctionFromToken` method returns a CORDBG_E_FUNCTION_NOT_IL HRESULT if the value passed in `methodDef` does not refer to a common intermediate language (CIL) method. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugmodule2-applychanges-method.md b/docs/framework/unmanaged-api/debugging/icordebugmodule2-applychanges-method.md index 67fa5b280e31e..91ab4017f4cb1 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmodule2-applychanges-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmodule2-applychanges-method.md @@ -2,70 +2,70 @@ description: "Learn more about: ICorDebugModule2::ApplyChanges Method" title: "ICorDebugModule2::ApplyChanges Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugModule2.ApplyChanges" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugModule2::ApplyChanges" -helpviewer_keywords: +helpviewer_keywords: - "ApplyChanges method [.NET Framework debugging]" - "ICorDebugModule2::ApplyChanges method [.NET Framework debugging]" ms.assetid: 96fa3406-6a6f-41a1-88c6-d9bc5d1a16d1 -topic_type: +topic_type: - "apiref" --- # ICorDebugModule2::ApplyChanges Method -Applies the changes in the metadata and the changes in the Microsoft intermediate language (MSIL) code to the running process. - -## Syntax - -```cpp -HRESULT ApplyChanges ( - [in] ULONG cbMetadata, - [in, size_is(cbMetadata)] BYTE pbMetadata[], - [in] ULONG cbIL, - [in, size_is(cbIL)] BYTE pbIL[] -); -``` - -## Parameters - - `cbMetadata` - [in] Size, in bytes, of the delta metadata. - - `pbMetadata` - [in] Buffer that contains the delta metadata. The address of the buffer is returned from the [IMetaDataEmit2::SaveDeltaToMemory](../metadata/imetadataemit2-savedeltatomemory-method.md) method. - - The relative virtual addresses (RVAs) in the metadata should be relative to the start of the MSIL code. - - `cbIL` - [in] Size, in bytes, of the delta MSIL code. - - `pbIL` - [in] Buffer that contains the updated MSIL code. - -## Remarks - - The `pbMetadata` parameter is in a special delta metadata format (as output by [IMetaDataEmit2::SaveDeltaToMemory](../metadata/imetadataemit2-savedeltatomemory-method.md)). `pbMetadata` takes previous metadata as a base and describes individual changes to apply to that base. - - In contrast, the `pbIL[`] parameter contains the new MSIL for the updated method, and is meant to completely replace the previous MSIL for that method - - When the delta MSIL and the metadata have been created in the debugger’s memory, the debugger calls `ApplyChanges` to send the changes into the common language runtime (CLR). The runtime updates its metadata tables, places the new MSIL into the process, and sets up a just-in-time (JIT) compilation of the new MSIL. When the changes have been applied, the debugger should call [IMetaDataEmit2::ResetENCLog](../metadata/imetadataemit2-resetenclog-method.md) to prepare for the next editing session. The debugger may then continue the process. - - Whenever the debugger calls `ApplyChanges` on a module that has delta metadata, it should also call [IMetaDataEmit::ApplyEditAndContinue](../metadata/imetadataemit-applyeditandcontinue-method.md) with the same delta metadata on all of its copies of that module’s metadata except for the copy used to emit the changes. If a copy of the metadata somehow becomes out-of-sync with the actual metadata, the debugger can always throw away that copy and obtain a new copy. - - If the `ApplyChanges` method fails, the debug session is in an invalid state and must be restarted. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Applies the changes in the metadata and the changes in the common intermediate language (CIL) code to the running process. + +## Syntax + +```cpp +HRESULT ApplyChanges ( + [in] ULONG cbMetadata, + [in, size_is(cbMetadata)] BYTE pbMetadata[], + [in] ULONG cbIL, + [in, size_is(cbIL)] BYTE pbIL[] +); +``` + +## Parameters + + `cbMetadata` + [in] Size, in bytes, of the delta metadata. + + `pbMetadata` + [in] Buffer that contains the delta metadata. The address of the buffer is returned from the [IMetaDataEmit2::SaveDeltaToMemory](../metadata/imetadataemit2-savedeltatomemory-method.md) method. + + The relative virtual addresses (RVAs) in the metadata should be relative to the start of the CIL code. + + `cbIL` + [in] Size, in bytes, of the delta CIL code. + + `pbIL` + [in] Buffer that contains the updated CIL code. + +## Remarks + + The `pbMetadata` parameter is in a special delta metadata format (as output by [IMetaDataEmit2::SaveDeltaToMemory](../metadata/imetadataemit2-savedeltatomemory-method.md)). `pbMetadata` takes previous metadata as a base and describes individual changes to apply to that base. + + In contrast, the `pbIL[`] parameter contains the new CIL for the updated method, and is meant to completely replace the previous CIL for that method + + When the delta CIL and the metadata have been created in the debugger’s memory, the debugger calls `ApplyChanges` to send the changes into the common language runtime (CLR). The runtime updates its metadata tables, places the new CIL into the process, and sets up a just-in-time (JIT) compilation of the new CIL. When the changes have been applied, the debugger should call [IMetaDataEmit2::ResetENCLog](../metadata/imetadataemit2-resetenclog-method.md) to prepare for the next editing session. The debugger may then continue the process. + + Whenever the debugger calls `ApplyChanges` on a module that has delta metadata, it should also call [IMetaDataEmit::ApplyEditAndContinue](../metadata/imetadataemit-applyeditandcontinue-method.md) with the same delta metadata on all of its copies of that module’s metadata except for the copy used to emit the changes. If a copy of the metadata somehow becomes out-of-sync with the actual metadata, the debugger can always throw away that copy and obtain a new copy. + + If the `ApplyChanges` method fails, the debug session is in an invalid state and must be restarted. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugmodule2-interface.md b/docs/framework/unmanaged-api/debugging/icordebugmodule2-interface.md index caf3ba6faf4d1..6adf72f0e41aa 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmodule2-interface.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmodule2-interface.md @@ -2,49 +2,49 @@ description: "Learn more about: ICorDebugModule2 Interface" title: "ICorDebugModule2 Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugModule2" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugModule2" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugModule2 interface [.NET Framework debugging]" ms.assetid: 0847e64f-fdbe-4c96-8168-da20fdc84d80 -topic_type: +topic_type: - "apiref" --- # ICorDebugModule2 Interface -Serves as a logical extension to the ICorDebugModule interface. - -## Methods - -|Method|Description| -|------------|-----------------| -|[ApplyChanges Method](icordebugmodule2-applychanges-method.md)|Applies the changes in the metadata and the changes in the Microsoft intermediate language (MSIL) code to the running process.| -|[GetJITCompilerFlags Method](icordebugmodule2-getjitcompilerflags-method.md)|Gets the flags that control the just-in-time (JIT) compilation for this `ICorDebugModule2`.| -|[ResolveAssembly Method](icordebugmodule2-resolveassembly-method.md)|Resolves the assembly referenced by the specified metadata token.| -|[SetJITCompilerFlags Method](icordebugmodule2-setjitcompilerflags-method.md)|Sets the flags that control the JIT compilation for this `ICorDebugModule2`.| -|[SetJMCStatus Method](icordebugmodule2-setjmcstatus-method.md)|Sets the Just My Code (JMC) status of all methods of all the classes in this `ICorDebugModule2` to the specified value, except those in the `pTokens` array, which it sets to the opposite value.| - -## Remarks - +Serves as a logical extension to the ICorDebugModule interface. + +## Methods + +|Method|Description| +|------------|-----------------| +|[ApplyChanges Method](icordebugmodule2-applychanges-method.md)|Applies the changes in the metadata and the changes in the common intermediate language (CIL) code to the running process.| +|[GetJITCompilerFlags Method](icordebugmodule2-getjitcompilerflags-method.md)|Gets the flags that control the just-in-time (JIT) compilation for this `ICorDebugModule2`.| +|[ResolveAssembly Method](icordebugmodule2-resolveassembly-method.md)|Resolves the assembly referenced by the specified metadata token.| +|[SetJITCompilerFlags Method](icordebugmodule2-setjitcompilerflags-method.md)|Sets the flags that control the JIT compilation for this `ICorDebugModule2`.| +|[SetJMCStatus Method](icordebugmodule2-setjmcstatus-method.md)|Sets the Just My Code (JMC) status of all methods of all the classes in this `ICorDebugModule2` to the specified value, except those in the `pTokens` array, which it sets to the opposite value.| + +## Remarks + > [!NOTE] -> This interface does not support being called remotely, either cross-machine or cross-process. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +> This interface does not support being called remotely, either cross-machine or cross-process. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [Debugging Interfaces](debugging-interfaces.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugprocess-readmemory-method.md b/docs/framework/unmanaged-api/debugging/icordebugprocess-readmemory-method.md index d0e65756e4c23..43249b1e78706 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugprocess-readmemory-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugprocess-readmemory-method.md @@ -2,63 +2,63 @@ description: "Learn more about: ICorDebugProcess::ReadMemory Method" title: "ICorDebugProcess::ReadMemory Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugProcess.ReadMemory" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugProcess::ReadMemory" -helpviewer_keywords: +helpviewer_keywords: - "ReadMemory method [.NET Framework debugging]" - "ICorDebugProcess::ReadMemory method [.NET Framework debugging]" ms.assetid: 28e4b2f6-9589-445c-be24-24a3306795e7 -topic_type: +topic_type: - "apiref" --- # ICorDebugProcess::ReadMemory Method -Reads a specified area of memory for this process. - -## Syntax - -```cpp -HRESULT ReadMemory( +Reads a specified area of memory for this process. + +## Syntax + +```cpp +HRESULT ReadMemory( [in] CORDB_ADDRESS address, - [in] DWORD size, - [out, size_is(size), length_is(size)] BYTE buffer[], - [out] SIZE_T *read); -``` - -## Parameters - - `address` - [in] A `CORDB_ADDRESS` value that specifies the base address of the memory to be read. - - `size` - [in] The number of bytes to be read from memory. - - `buffer` - [out] A buffer that receives the contents of the memory. - - `read` - [out] A pointer to the number of bytes transferred into the specified buffer. - -## Remarks - - The `ReadMemory` method is primarily intended to be used by interop debugging to inspect memory regions that are being used by the unmanaged portion of the debuggee. This method can also be used to read Microsoft intermediate language (MSIL) code and native JIT-compiled code. - - Any managed breakpoints will be removed from the data that is returned in the `buffer` parameter. No adjustments will be made for native breakpoints set by [ICorDebugProcess2::SetUnmanagedBreakpoint](icordebugprocess2-setunmanagedbreakpoint-method.md). - - No caching of process memory is performed. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - + [in] DWORD size, + [out, size_is(size), length_is(size)] BYTE buffer[], + [out] SIZE_T *read); +``` + +## Parameters + + `address` + [in] A `CORDB_ADDRESS` value that specifies the base address of the memory to be read. + + `size` + [in] The number of bytes to be read from memory. + + `buffer` + [out] A buffer that receives the contents of the memory. + + `read` + [out] A pointer to the number of bytes transferred into the specified buffer. + +## Remarks + + The `ReadMemory` method is primarily intended to be used by interop debugging to inspect memory regions that are being used by the unmanaged portion of the debuggee. This method can also be used to read common intermediate language (CIL) code and native JIT-compiled code. + + Any managed breakpoints will be removed from the data that is returned in the `buffer` parameter. No adjustments will be made for native breakpoints set by [ICorDebugProcess2::SetUnmanagedBreakpoint](icordebugprocess2-setunmanagedbreakpoint-method.md). + + No caching of process memory is performed. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugprocess2-setdesiredngencompilerflags-method.md b/docs/framework/unmanaged-api/debugging/icordebugprocess2-setdesiredngencompilerflags-method.md index 8652479fc6ba7..64568884aaf8e 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugprocess2-setdesiredngencompilerflags-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugprocess2-setdesiredngencompilerflags-method.md @@ -2,56 +2,56 @@ description: "Learn more about: ICorDebugProcess2::SetDesiredNGENCompilerFlags Method" title: "ICorDebugProcess2::SetDesiredNGENCompilerFlags Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugProcess2.SetDesiredNGENCompilerFlags" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugProcess2::SetDesiredNGENCompilerFlags" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugProcess2::SetDesiredNGENCompilerFlags method [.NET Framework debugging]" - "SetDesiredNGENCompilerFlags method [.NET Framework debugging]" ms.assetid: 98320175-7c5e-4dbb-8683-86fa82e2641f -topic_type: +topic_type: - "apiref" --- # ICorDebugProcess2::SetDesiredNGENCompilerFlags Method -Sets the flags that must be embedded in a precompiled image in order for the runtime to load that image into the current process. - -## Syntax - -```cpp -HRESULT SetDesiredNGENCompilerFlags ( - [in] DWORD pdwFlags -); -``` - -## Parameters - - `pdwFlags` - [in] A value of the [CorDebugJITCompilerFlags](cordebugjitcompilerflags-enumeration.md) enumeration that specifies the compiler flags used to select the correct pre-compiled image. - -## Remarks - - The `SetDesiredNGENCompilerFlags` method specifies the flags that must be embedded in a precompiled image so that the runtime will load that image into this process. The flags set by this method are used only to select the correct precompiled image. If no such image exists, the runtime will load the Microsoft intermediate language (MSIL) image and the just-in-time (JIT) compiler instead. In that case, the debugger must still use the [ICorDebugModule2::SetJITCompilerFlags](icordebugmodule2-setjitcompilerflags-method.md) method to set the flags as desired for the JIT compilation. - - If an image is loaded, but some JIT compiling must take place for that image (which will be the case if the image contains generics), the compiler flags specified by the `SetDesiredNGENCompilerFlags` method will apply to the extra JIT compilation. - - The `SetDesiredNGENCompilerFlags` method must be called during the [ICorDebugManagedCallback::CreateProcess](icordebugmanagedcallback-createprocess-method.md) callback. Attempts to call the `SetDesiredNGENCompilerFlags` method afterwards will fail. Also, attempts to set flags that are either not defined in the `CorDebugJITCompilerFlags` enumeration or are not legal for the given process will fail. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Sets the flags that must be embedded in a precompiled image in order for the runtime to load that image into the current process. + +## Syntax + +```cpp +HRESULT SetDesiredNGENCompilerFlags ( + [in] DWORD pdwFlags +); +``` + +## Parameters + + `pdwFlags` + [in] A value of the [CorDebugJITCompilerFlags](cordebugjitcompilerflags-enumeration.md) enumeration that specifies the compiler flags used to select the correct pre-compiled image. + +## Remarks + + The `SetDesiredNGENCompilerFlags` method specifies the flags that must be embedded in a precompiled image so that the runtime will load that image into this process. The flags set by this method are used only to select the correct precompiled image. If no such image exists, the runtime will load the common intermediate language (CIL) image and the just-in-time (JIT) compiler instead. In that case, the debugger must still use the [ICorDebugModule2::SetJITCompilerFlags](icordebugmodule2-setjitcompilerflags-method.md) method to set the flags as desired for the JIT compilation. + + If an image is loaded, but some JIT compiling must take place for that image (which will be the case if the image contains generics), the compiler flags specified by the `SetDesiredNGENCompilerFlags` method will apply to the extra JIT compilation. + + The `SetDesiredNGENCompilerFlags` method must be called during the [ICorDebugManagedCallback::CreateProcess](icordebugmanagedcallback-createprocess-method.md) callback. Attempts to call the `SetDesiredNGENCompilerFlags` method afterwards will fail. Also, attempts to set flags that are either not defined in the `CorDebugJITCompilerFlags` enumeration or are not legal for the given process will fail. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorDebug Interface](icordebug-interface.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugstepper-interface.md b/docs/framework/unmanaged-api/debugging/icordebugstepper-interface.md index d71b2c69db957..88e9b8ac1f94f 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugstepper-interface.md +++ b/docs/framework/unmanaged-api/debugging/icordebugstepper-interface.md @@ -2,64 +2,64 @@ description: "Learn more about: ICorDebugStepper Interface" title: "ICorDebugStepper Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugStepper" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugStepper" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugStepper interface [.NET Framework debugging]" ms.assetid: ed8364eb-f01b-46f6-b5e3-5dda9cae2dfe -topic_type: +topic_type: - "apiref" --- # ICorDebugStepper Interface -Represents a step in code execution that is performed by a debugger, serves as an identifier between the issuance and completion of a command, and provides a way to cancel a step. - -## Methods - -|Method|Description| -|------------|-----------------| -|[Deactivate Method](icordebugstepper-deactivate-method.md)|Causes this `ICorDebugStepper` to cancel the last step command it received.| -|[IsActive Method](icordebugstepper-isactive-method.md)|Gets a value that indicates whether this `ICorDebugStepper` is currently executing a step.| -|[SetInterceptMask Method](icordebugstepper-setinterceptmask-method.md)|Sets a CorDebugIntercept value that specifies the types of code that are stepped into.| -|[SetRangeIL Method](icordebugstepper-setrangeil-method.md)|Sets a value that indicates whether calls to [ICorDebugStepper::StepRange](icordebugstepper-steprange-method.md) pass argument values relative to the native code or to Microsoft intermediate language (MSIL) code of the method that is being stepped through.| -|[SetUnmappedStopMask Method](icordebugstepper-setunmappedstopmask-method.md)|Sets a CorDebugUnmappedStop value that specifies the type of unmapped code in which execution will halt.| -|[Step Method](icordebugstepper-step-method.md)|Causes this `ICorDebugStepper` to single-step through its containing thread, and optionally, to continue single-stepping through functions that are called within the thread.| -|[StepOut Method](icordebugstepper-stepout-method.md)|Causes this `ICorDebugStepper` to single-step through its containing thread, and to complete when the current frame returns control to the calling frame.| -|[StepRange Method](icordebugstepper-steprange-method.md)|Causes this `ICorDebugStepper` to single-step through its containing thread, and to return when it reaches code beyond the last of the specified ranges.| - -## Remarks - - The `ICorDebugStepper` interface serves the following purposes: - -- It acts as an identifier between a step command that is issued and the completion of that command. - -- It provides a central interface to encapsulate all the stepping that can be performed. - -- It provides a way to prematurely cancel a stepping operation. - - There can be more than one stepper per thread. For example, a breakpoint may be hit while stepping over a function, and the user may wish to start a new stepping operation inside that function. It is up to the debugger to determine how to handle this situation. The debugger may want to cancel the original stepping operation or nest the two operations. The `ICorDebugStepper` interface supports both choices. - - A stepper may migrate between threads if the common language runtime (CLR) makes a cross-threaded, marshalled call. - +Represents a step in code execution that is performed by a debugger, serves as an identifier between the issuance and completion of a command, and provides a way to cancel a step. + +## Methods + +|Method|Description| +|------------|-----------------| +|[Deactivate Method](icordebugstepper-deactivate-method.md)|Causes this `ICorDebugStepper` to cancel the last step command it received.| +|[IsActive Method](icordebugstepper-isactive-method.md)|Gets a value that indicates whether this `ICorDebugStepper` is currently executing a step.| +|[SetInterceptMask Method](icordebugstepper-setinterceptmask-method.md)|Sets a CorDebugIntercept value that specifies the types of code that are stepped into.| +|[SetRangeIL Method](icordebugstepper-setrangeil-method.md)|Sets a value that indicates whether calls to [ICorDebugStepper::StepRange](icordebugstepper-steprange-method.md) pass argument values relative to the native code or to common intermediate language (CIL) code of the method that is being stepped through.| +|[SetUnmappedStopMask Method](icordebugstepper-setunmappedstopmask-method.md)|Sets a CorDebugUnmappedStop value that specifies the type of unmapped code in which execution will halt.| +|[Step Method](icordebugstepper-step-method.md)|Causes this `ICorDebugStepper` to single-step through its containing thread, and optionally, to continue single-stepping through functions that are called within the thread.| +|[StepOut Method](icordebugstepper-stepout-method.md)|Causes this `ICorDebugStepper` to single-step through its containing thread, and to complete when the current frame returns control to the calling frame.| +|[StepRange Method](icordebugstepper-steprange-method.md)|Causes this `ICorDebugStepper` to single-step through its containing thread, and to return when it reaches code beyond the last of the specified ranges.| + +## Remarks + + The `ICorDebugStepper` interface serves the following purposes: + +- It acts as an identifier between a step command that is issued and the completion of that command. + +- It provides a central interface to encapsulate all the stepping that can be performed. + +- It provides a way to prematurely cancel a stepping operation. + + There can be more than one stepper per thread. For example, a breakpoint may be hit while stepping over a function, and the user may wish to start a new stepping operation inside that function. It is up to the debugger to determine how to handle this situation. The debugger may want to cancel the original stepping operation or nest the two operations. The `ICorDebugStepper` interface supports both choices. + + A stepper may migrate between threads if the common language runtime (CLR) makes a cross-threaded, marshalled call. + > [!NOTE] -> This interface does not support being called remotely, either cross-machine or cross-process. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +> This interface does not support being called remotely, either cross-machine or cross-process. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [Debugging Interfaces](debugging-interfaces.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugstepper-setrangeil-method.md b/docs/framework/unmanaged-api/debugging/icordebugstepper-setrangeil-method.md index 4988d2b6b70b3..0050f0e2e9f7d 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugstepper-setrangeil-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugstepper-setrangeil-method.md @@ -2,44 +2,44 @@ description: "Learn more about: ICorDebugStepper::SetRangeIL Method" title: "ICorDebugStepper::SetRangeIL Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugStepper.SetRangeIL" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugStepper::SetRangeIL" -helpviewer_keywords: +helpviewer_keywords: - "SetRangeIL method [.NET Framework debugging]" - "ICorDebugStepper::SetRangeIL method [.NET Framework debugging]" ms.assetid: a20c95f0-6da7-4b41-b27f-584211cebb92 -topic_type: +topic_type: - "apiref" --- # ICorDebugStepper::SetRangeIL Method -Sets a value that specifies whether calls to [ICorDebugStepper::StepRange](icordebugstepper-steprange-method.md) pass argument values that are relative to the native code or relative to Microsoft intermediate language (MSIL) code of the method that is being stepped through. - -## Syntax - -```cpp -HRESULT SetRangeIL ( - [in] BOOL bIL -); -``` - -## Parameters - - `bIL` - [in] Set to `true` to specify that the ranges are relative to the MSIL code. Set to `false` to specify that the ranges are relative to the native code. The default value is `true`. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Sets a value that specifies whether calls to [ICorDebugStepper::StepRange](icordebugstepper-steprange-method.md) pass argument values that are relative to the native code or relative to common intermediate language (CIL) code of the method that is being stepped through. + +## Syntax + +```cpp +HRESULT SetRangeIL ( + [in] BOOL bIL +); +``` + +## Parameters + + `bIL` + [in] Set to `true` to specify that the ranges are relative to the CIL code. Set to `false` to specify that the ranges are relative to the native code. The default value is `true`. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugstepper-setunmappedstopmask-method.md b/docs/framework/unmanaged-api/debugging/icordebugstepper-setunmappedstopmask-method.md index f4ed3a6170c4a..b4f8d7089cb0a 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugstepper-setunmappedstopmask-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugstepper-setunmappedstopmask-method.md @@ -2,52 +2,52 @@ description: "Learn more about: ICorDebugStepper::SetUnmappedStopMask Method" title: "ICorDebugStepper::SetUnmappedStopMask Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugStepper.SetUnmappedStopMask" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugStepper::SetUnmappedStopMask" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugStepper::SetUnmappedStopMask method [.NET Framework debugging]" - "SetUnmappedStopMask method [.NET Framework debugging]" ms.assetid: b1211981-e90c-4e05-8def-fa18d85ad9ab -topic_type: +topic_type: - "apiref" --- # ICorDebugStepper::SetUnmappedStopMask Method -Sets a value that specifies the type of unmapped code in which execution will halt. - -## Syntax - -```cpp -HRESULT SetUnmappedStopMask ( - [in] CorDebugUnmappedStop mask -); -``` - -## Parameters - - `mask` - [in] A value of the CorDebugUnmappedStop enumeration that specifies the type of unmapped code in which the debugger will halt execution. - - The default value is STOP_OTHER_UNMAPPED. The value STOP_UNMANAGED is only valid with interop debugging. - -## Remarks - - When the debugger finds a just-in-time (JIT) compilation that has no corresponding mapping to Microsoft intermediate language (MSIL), it halts execution if the flag specifying that type of unmapped code has been set; otherwise, stepping transparently continues. - - If the debugger doesn't use a stepper to enter a method, then it won't necessarily step over unmapped code. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Sets a value that specifies the type of unmapped code in which execution will halt. + +## Syntax + +```cpp +HRESULT SetUnmappedStopMask ( + [in] CorDebugUnmappedStop mask +); +``` + +## Parameters + + `mask` + [in] A value of the CorDebugUnmappedStop enumeration that specifies the type of unmapped code in which the debugger will halt execution. + + The default value is STOP_OTHER_UNMAPPED. The value STOP_UNMANAGED is only valid with interop debugging. + +## Remarks + + When the debugger finds a just-in-time (JIT) compilation that has no corresponding mapping to common intermediate language (CIL), it halts execution if the flag specifying that type of unmapped code has been set; otherwise, stepping transparently continues. + + If the debugger doesn't use a stepper to enter a method, then it won't necessarily step over unmapped code. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugstepper-steprange-method.md b/docs/framework/unmanaged-api/debugging/icordebugstepper-steprange-method.md index 034f8ec4dd508..bf5b5372eab87 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugstepper-steprange-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugstepper-steprange-method.md @@ -2,60 +2,60 @@ description: "Learn more about: ICorDebugStepper::StepRange Method" title: "ICorDebugStepper::StepRange Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugStepper.StepRange" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugStepper::StepRange" -helpviewer_keywords: +helpviewer_keywords: - "StepRange method [.NET Framework debugging]" - "ICorDebugStepper::StepRange method [.NET Framework debugging]" ms.assetid: b9776112-6e6d-4708-892a-8873db02e16f -topic_type: +topic_type: - "apiref" --- # ICorDebugStepper::StepRange Method -Causes this ICorDebugStepper to single-step through its containing thread, and to return when it reaches code beyond the last of the specified ranges. - -## Syntax - -```cpp -HRESULT StepRange ( - [in] BOOL bStepIn, - [in, size_is(cRangeCount)] COR_DEBUG_STEP_RANGE ranges[], - [in] ULONG32 cRangeCount -); -``` - -## Parameters - - `bStepIn` - [in] Set to `true` to step into a function that is called within the thread. Set to `false` to step over the function. - - `ranges` - [in] An array of COR_DEBUG_STEP_RANGE structures, each of which specifies a range. - - `cRangeCount` - [in] The size of the `ranges` array. - -## Remarks - - The `StepRange` method works like the [ICorDebugStepper::Step](icordebugstepper-step-method.md) method, except that it does not complete until code outside the given range is reached. - - This can be more efficient than stepping one instruction at a time. Ranges are specified as a list of offset pairs from the start of the stepper's frame. - - Ranges are relative to the Microsoft intermediate language (MSIL) code of a method. Call [ICorDebugStepper::SetRangeIL](icordebugstepper-setrangeil-method.md) with `false` to make the ranges relative to the native code of a method. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Causes this ICorDebugStepper to single-step through its containing thread, and to return when it reaches code beyond the last of the specified ranges. + +## Syntax + +```cpp +HRESULT StepRange ( + [in] BOOL bStepIn, + [in, size_is(cRangeCount)] COR_DEBUG_STEP_RANGE ranges[], + [in] ULONG32 cRangeCount +); +``` + +## Parameters + + `bStepIn` + [in] Set to `true` to step into a function that is called within the thread. Set to `false` to step over the function. + + `ranges` + [in] An array of COR_DEBUG_STEP_RANGE structures, each of which specifies a range. + + `cRangeCount` + [in] The size of the `ranges` array. + +## Remarks + + The `StepRange` method works like the [ICorDebugStepper::Step](icordebugstepper-step-method.md) method, except that it does not complete until code outside the given range is reached. + + This can be more efficient than stepping one instruction at a time. Ranges are specified as a list of offset pairs from the start of the stepper's frame. + + Ranges are relative to the common intermediate language (CIL) code of a method. Call [ICorDebugStepper::SetRangeIL](icordebugstepper-setrangeil-method.md) with `false` to make the ranges relative to the native code of a method. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/diagnostics/corsymaddrkind-enumeration.md b/docs/framework/unmanaged-api/diagnostics/corsymaddrkind-enumeration.md index 2c2c80079f9cc..de1a498c4ff48 100644 --- a/docs/framework/unmanaged-api/diagnostics/corsymaddrkind-enumeration.md +++ b/docs/framework/unmanaged-api/diagnostics/corsymaddrkind-enumeration.md @@ -2,61 +2,61 @@ description: "Learn more about: CorSymAddrKind Enumeration" title: "CorSymAddrKind Enumeration" ms.date: "03/30/2017" -api_name: +api_name: - "CorSymAddrKind" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "CorSymAddrKind" -helpviewer_keywords: +helpviewer_keywords: - "CorSymAddrKind enumeration [.NET Framework debugging]" ms.assetid: 3ef841c2-cade-42ee-ba34-2ef91d6d0879 -topic_type: +topic_type: - "apiref" --- # CorSymAddrKind Enumeration -Indicates the type of memory address. - -## Syntax - -```cpp -typedef enum CorSymAddrKind -{ - ADDR_IL_OFFSET = 1, - ADDR_NATIVE_RVA = 2, - ADDR_NATIVE_REGISTER = 3, - ADDR_NATIVE_REGREL = 4, - ADDR_NATIVE_OFFSET = 5, - ADDR_NATIVE_REGREG = 6, - ADDR_NATIVE_REGSTK = 7, - ADDR_NATIVE_STKREG = 8, - ADDR_BITFIELD = 9, - ADDR_NATIVE_ISECTOFFSET = 10 -} CorSymAddrKind; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`ADDR_IL_OFFSET`|Indicates a Microsoft intermediate language (MSIL) local variable or parameter index.| -|`ADDR_NATIVE_RVA`|Indicates a relative virtual address into a module.| -|`ADDR_NATIVE_REGISTER`|Indicates a CPU register.| -|`ADDR_NATIVE_REGREL`|Indicates that the first address is a register and the second address is an offset.| -|`ADDR_NATIVE_OFFSET`|Indicates an offset from a base address.| -|`ADDR_NATIVE_REGREG`|Indicates that the first address is the low portion of a register, and the second address is the high portion.| -|`ADDR_NATIVE_REGSTK`|Indicates that the first address is the low portion of a register, the second is the high portion, and the third is an offset.| -|`ADDR_NATIVE_STKREG`|Indicates that the first address is a register, the second is an offset, and the third is the high portion of the register.| -|`ADDR_BITFIELD`|Indicates that the first address is the start of a field and the second address is the field length.| -|`ADDR_NATIVE_ISECTOFFSET`|Indicates that the first address is the section and the second address is an offset.| - -## Requirements - - **Header:** CorSym.idl, CorSym.h - +Indicates the type of memory address. + +## Syntax + +```cpp +typedef enum CorSymAddrKind +{ + ADDR_IL_OFFSET = 1, + ADDR_NATIVE_RVA = 2, + ADDR_NATIVE_REGISTER = 3, + ADDR_NATIVE_REGREL = 4, + ADDR_NATIVE_OFFSET = 5, + ADDR_NATIVE_REGREG = 6, + ADDR_NATIVE_REGSTK = 7, + ADDR_NATIVE_STKREG = 8, + ADDR_BITFIELD = 9, + ADDR_NATIVE_ISECTOFFSET = 10 +} CorSymAddrKind; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`ADDR_IL_OFFSET`|Indicates a common intermediate language (CIL) local variable or parameter index.| +|`ADDR_NATIVE_RVA`|Indicates a relative virtual address into a module.| +|`ADDR_NATIVE_REGISTER`|Indicates a CPU register.| +|`ADDR_NATIVE_REGREL`|Indicates that the first address is a register and the second address is an offset.| +|`ADDR_NATIVE_OFFSET`|Indicates an offset from a base address.| +|`ADDR_NATIVE_REGREG`|Indicates that the first address is the low portion of a register, and the second address is the high portion.| +|`ADDR_NATIVE_REGSTK`|Indicates that the first address is the low portion of a register, the second is the high portion, and the third is an offset.| +|`ADDR_NATIVE_STKREG`|Indicates that the first address is a register, the second is an offset, and the third is the high portion of the register.| +|`ADDR_BITFIELD`|Indicates that the first address is the start of a field and the second address is the field length.| +|`ADDR_NATIVE_ISECTOFFSET`|Indicates that the first address is the section and the second address is an offset.| + +## Requirements + + **Header:** CorSym.idl, CorSym.h + ## See also - [Diagnostics Symbol Store Enumerations](diagnostics-symbol-store-enumerations.md) diff --git a/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getranges-method.md b/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getranges-method.md index a8553a08ece93..e6e3d5b02af1e 100644 --- a/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getranges-method.md +++ b/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getranges-method.md @@ -2,66 +2,66 @@ description: "Learn more about: ISymUnmanagedMethod::GetRanges Method" title: "ISymUnmanagedMethod::GetRanges Method" ms.date: "03/30/2017" -api_name: +api_name: - "ISymUnmanagedMethod.GetRanges" -api_location: +api_location: - "diasymreader.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ISymUnmanagedMethod::GetRanges" -helpviewer_keywords: +helpviewer_keywords: - "ISymUnmanagedMethod::GetRanges method [.NET Framework debugging]" - "GetRanges method [.NET Framework debugging]" ms.assetid: a85283d8-379c-417a-9736-ddeeef9bcf50 -topic_type: +topic_type: - "apiref" --- # ISymUnmanagedMethod::GetRanges Method -Given a position in a document, returns an array of start and end offset pairs that correspond to the ranges of Microsoft intermediate language (MSIL) that the position covers within this method. The array is an array of integers and has the format [start, end, start, end]. The number of range pairs is the length of the array divided by 2. - -## Syntax - -```cpp -HRESULT GetRanges( - [in] ISymUnmanagedDocument* document, - [in] ULONG32 line, - [in] ULONG32 column, - [in] ULONG32 cRanges, - [out] ULONG32 *pcRanges, - [out, size_is(cRanges), - length_is(*pcRanges)] ULONG32 ranges[]); -``` - -## Parameters - - `document` - [in] The document for which the offset is requested. - - `line` - [in] The document line corresponding to the ranges. - - `column` - [in] The document column corresponding to the ranges. - - `cRanges` - [in] The size of the `ranges` array. - - `pcRanges` - [out] A pointer to a `ULONG32` that receives the size of the buffer required to contain the ranges. - - `ranges` - [out] A pointer to the buffer that receives the ranges. - -## Return Value - - S_OK if the method succeeds; otherwise, E_FAIL or some other error code. - -## Requirements - - **Header:** CorSym.idl, CorSym.h - +Given a position in a document, returns an array of start and end offset pairs that correspond to the ranges of common intermediate language (CIL) that the position covers within this method. The array is an array of integers and has the format [start, end, start, end]. The number of range pairs is the length of the array divided by 2. + +## Syntax + +```cpp +HRESULT GetRanges( + [in] ISymUnmanagedDocument* document, + [in] ULONG32 line, + [in] ULONG32 column, + [in] ULONG32 cRanges, + [out] ULONG32 *pcRanges, + [out, size_is(cRanges), + length_is(*pcRanges)] ULONG32 ranges[]); +``` + +## Parameters + + `document` + [in] The document for which the offset is requested. + + `line` + [in] The document line corresponding to the ranges. + + `column` + [in] The document column corresponding to the ranges. + + `cRanges` + [in] The size of the `ranges` array. + + `pcRanges` + [out] A pointer to a `ULONG32` that receives the size of the buffer required to contain the ranges. + + `ranges` + [out] A pointer to the buffer that receives the ranges. + +## Return Value + + S_OK if the method succeeds; otherwise, E_FAIL or some other error code. + +## Requirements + + **Header:** CorSym.idl, CorSym.h + ## See also - [ISymUnmanagedMethod Interface](isymunmanagedmethod-interface.md) diff --git a/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getsequencepoints-method.md b/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getsequencepoints-method.md index 606546fdafc98..d992f160444bd 100644 --- a/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getsequencepoints-method.md +++ b/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getsequencepoints-method.md @@ -2,73 +2,73 @@ description: "Learn more about: ISymUnmanagedMethod::GetSequencePoints Method" title: "ISymUnmanagedMethod::GetSequencePoints Method" ms.date: "03/30/2017" -api_name: +api_name: - "ISymUnmanagedMethod.GetSequencePoints" -api_location: +api_location: - "diasymreader.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ISymUnmanagedMethod::GetSequencePoints" -helpviewer_keywords: +helpviewer_keywords: - "ISymUnmanagedMethod::GetSequencePoints method [.NET Framework debugging]" - "GetSequencePoints method [.NET Framework debugging]" ms.assetid: f909ac48-3d8f-49fb-a369-e3d9959151cd -topic_type: +topic_type: - "apiref" --- # ISymUnmanagedMethod::GetSequencePoints Method -Gets all the sequence points within this method. - -## Syntax - -```cpp -HRESULT GetSequencePoints( - [in] ULONG32 cPoints, - [out] ULONG32 *pcPoints, - [in, size_is(cPoints)] ULONG32 offsets[], - [in, size_is(cPoints)] ISymUnmanagedDocument* documents[], - [in, size_is(cPoints)] ULONG32 lines[], - [in, size_is(cPoints)] ULONG32 columns[], - [in, size_is(cPoints)] ULONG32 endLines[], - [in, size_is(cPoints)] ULONG32 endColumns[]); -``` - -## Parameters - - `cPoints` - [in] A `ULONG32` that receives the size of the `offsets`, `documents`, `lines`, `columns`, `endLines`, and `endColumns` arrays. - - `pcPoints` - [out] A pointer to a `ULONG32` that receives the length of the buffer required to contain the sequence points. - - `offsets` - [in] An array in which to store the Microsoft intermediate language (MSIL) offsets from the beginning of the method for the sequence points. - - `documents` - [in] An array in which to store the documents in which the sequence points are located. - - `lines` - [in] An array in which to store the lines in the documents at which the sequence points are located. - - `columns` - [in] An array in which to store the columns in the documents at which the sequence points are located. - - `endLines` - [in] The array of lines in the documents at which the sequence points end. - - `endColumns` - [in] The array of columns in the documents at which the sequence points end. - -## Return Value - - S_OK if the method succeeds; otherwise, E_FAIL or some other error code. - -## Requirements - - **Header:** CorSym.idl, CorSym.h - +Gets all the sequence points within this method. + +## Syntax + +```cpp +HRESULT GetSequencePoints( + [in] ULONG32 cPoints, + [out] ULONG32 *pcPoints, + [in, size_is(cPoints)] ULONG32 offsets[], + [in, size_is(cPoints)] ISymUnmanagedDocument* documents[], + [in, size_is(cPoints)] ULONG32 lines[], + [in, size_is(cPoints)] ULONG32 columns[], + [in, size_is(cPoints)] ULONG32 endLines[], + [in, size_is(cPoints)] ULONG32 endColumns[]); +``` + +## Parameters + + `cPoints` + [in] A `ULONG32` that receives the size of the `offsets`, `documents`, `lines`, `columns`, `endLines`, and `endColumns` arrays. + + `pcPoints` + [out] A pointer to a `ULONG32` that receives the length of the buffer required to contain the sequence points. + + `offsets` + [in] An array in which to store the common intermediate language (CIL) offsets from the beginning of the method for the sequence points. + + `documents` + [in] An array in which to store the documents in which the sequence points are located. + + `lines` + [in] An array in which to store the lines in the documents at which the sequence points are located. + + `columns` + [in] An array in which to store the columns in the documents at which the sequence points are located. + + `endLines` + [in] The array of lines in the documents at which the sequence points end. + + `endColumns` + [in] The array of columns in the documents at which the sequence points end. + +## Return Value + + S_OK if the method succeeds; otherwise, E_FAIL or some other error code. + +## Requirements + + **Header:** CorSym.idl, CorSym.h + ## See also - [ISymUnmanagedMethod Interface](isymunmanagedmethod-interface.md) diff --git a/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-interface.md b/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-interface.md index 5d525925a1027..1ff575cf0e7aa 100644 --- a/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-interface.md +++ b/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-interface.md @@ -2,43 +2,43 @@ description: "Learn more about: ISymUnmanagedMethod Interface" title: "ISymUnmanagedMethod Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ISymUnmanagedMethod" -api_location: +api_location: - "diasymreader.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ISymUnmanagedMethod" -helpviewer_keywords: +helpviewer_keywords: - "ISymUnmanagedMethod interface [.NET Framework debugging]" ms.assetid: f204d74c-cc79-4092-83bb-60654be95649 -topic_type: +topic_type: - "apiref" --- # ISymUnmanagedMethod Interface -Represents a method within the symbol store. This interface provides access to only the symbol-related attributes of a method, instead of the type-related attributes. - -## Methods - -|Method|Description| -|------------|-----------------| -|[GetNamespace Method](isymunmanagedmethod-getnamespace-method.md)|Gets the namespace within which this method is defined.| -|[GetOffset Method](isymunmanagedmethod-getoffset-method.md)|Returns the offset within this method that corresponds to a given position within a document.| -|[GetParameters Method](isymunmanagedmethod-getparameters-method.md)|Gets the parameters for this method.| -|[GetRanges Method](isymunmanagedmethod-getranges-method.md)|Given a position in a document, returns an array of start and end offset pairs that correspond to the ranges of Microsoft intermediate language (MSIL) that the position covers within this method.| -|[GetRootScope Method](isymunmanagedmethod-getrootscope-method.md)|Gets the root lexical scope within this method. This scope encloses the entire method.| -|[GetScopeFromOffset Method](isymunmanagedmethod-getscopefromoffset-method.md)|Gets the most enclosing lexical scope within this method that encloses the given offset.| -|[GetSequencePointCount Method](isymunmanagedmethod-getsequencepointcount-method.md)|Gets the count of sequence points within this method.| -|[GetSequencePoints Method](isymunmanagedmethod-getsequencepoints-method.md)|Gets all the sequence points within this method.| -|[GetSourceStartEnd Method](isymunmanagedmethod-getsourcestartend-method.md)|Gets the start and end document positions for the source of this method.| -|[GetToken Method](isymunmanagedmethod-gettoken-method.md)|Returns the metadata token for this method.| - -## Requirements +Represents a method within the symbol store. This interface provides access to only the symbol-related attributes of a method, instead of the type-related attributes. + +## Methods + +|Method|Description| +|------------|-----------------| +|[GetNamespace Method](isymunmanagedmethod-getnamespace-method.md)|Gets the namespace within which this method is defined.| +|[GetOffset Method](isymunmanagedmethod-getoffset-method.md)|Returns the offset within this method that corresponds to a given position within a document.| +|[GetParameters Method](isymunmanagedmethod-getparameters-method.md)|Gets the parameters for this method.| +|[GetRanges Method](isymunmanagedmethod-getranges-method.md)|Given a position in a document, returns an array of start and end offset pairs that correspond to the ranges of common intermediate language (CIL) that the position covers within this method.| +|[GetRootScope Method](isymunmanagedmethod-getrootscope-method.md)|Gets the root lexical scope within this method. This scope encloses the entire method.| +|[GetScopeFromOffset Method](isymunmanagedmethod-getscopefromoffset-method.md)|Gets the most enclosing lexical scope within this method that encloses the given offset.| +|[GetSequencePointCount Method](isymunmanagedmethod-getsequencepointcount-method.md)|Gets the count of sequence points within this method.| +|[GetSequencePoints Method](isymunmanagedmethod-getsequencepoints-method.md)|Gets all the sequence points within this method.| +|[GetSourceStartEnd Method](isymunmanagedmethod-getsourcestartend-method.md)|Gets the start and end document positions for the source of this method.| +|[GetToken Method](isymunmanagedmethod-gettoken-method.md)|Returns the metadata token for this method.| + +## Requirements + + **Header:** CorSym.idl, CorSym.h - **Header:** CorSym.idl, CorSym.h - ## See also - [Diagnostics Symbol Store Interfaces](diagnostics-symbol-store-interfaces.md) diff --git a/docs/framework/unmanaged-api/hosting/iclrprobingassemblyenum-get-method.md b/docs/framework/unmanaged-api/hosting/iclrprobingassemblyenum-get-method.md index 39e58fa96b27a..423f93c02a248 100644 --- a/docs/framework/unmanaged-api/hosting/iclrprobingassemblyenum-get-method.md +++ b/docs/framework/unmanaged-api/hosting/iclrprobingassemblyenum-get-method.md @@ -2,75 +2,75 @@ description: "Learn more about: ICLRProbingAssemblyEnum::Get Method" title: "ICLRProbingAssemblyEnum::Get Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICLRProbingAssemblyEnum.Get" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICLRProbingAssemblyEnum::Get" -helpviewer_keywords: +helpviewer_keywords: - "Get method, ICLRProbingAssemblyEnum interface [.NET Framework hosting]" - "ICLRProbingAssemblyEnum::Get method [.NET Framework hosting]" ms.assetid: fdb67a77-782f-44cf-a8a1-b75999b0f3c8 -topic_type: +topic_type: - "apiref" --- # ICLRProbingAssemblyEnum::Get Method -Gets the assembly identity at the specified index. - -## Syntax - -```cpp -HRESULT Get ( - [in] DWORD dwIndex, - [out, size_is(*pcchBufferSize)] LPWSTR pwzBuffer, - [in, out] DWORD *pcchBufferSize -); -``` - -## Parameters - - `dwIndex` - [in] The zero-based index of the assembly identity to return. - - `pwzBuffer` - [out] A buffer containing the assembly identity data. - - `pcchBufferSize` - [in, out] The size of the `pwzBuffer` buffer. - -## Return Value - -|HRESULT|Description| -|-------------|-----------------| -|S_OK|`Get` returned successfully.| -|ERROR_INSUFFICIENT_BUFFER|`pwzBuffer` is too small.| -|ERROR_NO_MORE_ITEMS|The enumeration contains no more items.| -|HOST_E_CLRNOTAVAILABLE|The common language runtime (CLR) has not been loaded into a process, or the CLR is in a state in which it cannot run managed code or process the call successfully.| -|HOST_E_TIMEOUT|The call timed out.| -|HOST_E_NOT_OWNER|The caller does not own the lock.| -|HOST_E_ABANDONED|An event was canceled while a blocked thread or fiber was waiting on it.| -|E_FAIL|An unknown catastrophic failure occurred. If a method returns E_FAIL, the CLR is no longer usable within the process. Subsequent calls to any hosting methods return HOST_E_CLRNOTAVAILABLE.| - -## Remarks - - The identity at index 0 is the identity specific to the processor architecture. The identity at index 1 is the architecture-neutral assembly for Microsoft intermediate language (MSIL). The identity at index 2 contains no architecture information. - - `Get` is typically called twice. The first call supplies a null value for `pwzBuffer`, and sets `pcchBufferSize` to the size appropriate for `pwzBuffer`. The second call supplies an appropriately sized `pwzBuffer`, and contains the canonical assembly identity data upon completion. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** MSCorEE.h - - **Library:** Included as a resource in MSCorEE.dll - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Gets the assembly identity at the specified index. + +## Syntax + +```cpp +HRESULT Get ( + [in] DWORD dwIndex, + [out, size_is(*pcchBufferSize)] LPWSTR pwzBuffer, + [in, out] DWORD *pcchBufferSize +); +``` + +## Parameters + + `dwIndex` + [in] The zero-based index of the assembly identity to return. + + `pwzBuffer` + [out] A buffer containing the assembly identity data. + + `pcchBufferSize` + [in, out] The size of the `pwzBuffer` buffer. + +## Return Value + +|HRESULT|Description| +|-------------|-----------------| +|S_OK|`Get` returned successfully.| +|ERROR_INSUFFICIENT_BUFFER|`pwzBuffer` is too small.| +|ERROR_NO_MORE_ITEMS|The enumeration contains no more items.| +|HOST_E_CLRNOTAVAILABLE|The common language runtime (CLR) has not been loaded into a process, or the CLR is in a state in which it cannot run managed code or process the call successfully.| +|HOST_E_TIMEOUT|The call timed out.| +|HOST_E_NOT_OWNER|The caller does not own the lock.| +|HOST_E_ABANDONED|An event was canceled while a blocked thread or fiber was waiting on it.| +|E_FAIL|An unknown catastrophic failure occurred. If a method returns E_FAIL, the CLR is no longer usable within the process. Subsequent calls to any hosting methods return HOST_E_CLRNOTAVAILABLE.| + +## Remarks + + The identity at index 0 is the identity specific to the processor architecture. The identity at index 1 is the architecture-neutral assembly for common intermediate language (CIL). The identity at index 2 contains no architecture information. + + `Get` is typically called twice. The first call supplies a null value for `pwzBuffer`, and sets `pcchBufferSize` to the size appropriate for `pwzBuffer`. The second call supplies an appropriately sized `pwzBuffer`, and contains the canonical assembly identity data upon completion. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** MSCorEE.h + + **Library:** Included as a resource in MSCorEE.dll + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICLRProbingAssemblyEnum Interface](iclrprobingassemblyenum-interface.md) diff --git a/docs/framework/unmanaged-api/hosting/iclrvalidator-interface.md b/docs/framework/unmanaged-api/hosting/iclrvalidator-interface.md index a799a184bfd9d..3caf8c9b0279a 100644 --- a/docs/framework/unmanaged-api/hosting/iclrvalidator-interface.md +++ b/docs/framework/unmanaged-api/hosting/iclrvalidator-interface.md @@ -2,41 +2,41 @@ description: "Learn more about: ICLRValidator Interface" title: "ICLRValidator Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICLRValidator" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICLRValidator" -helpviewer_keywords: +helpviewer_keywords: - "ICLRValidator interface [.NET Framework hosting]" ms.assetid: 2edd0a10-77fb-4173-91eb-f2970cc364d0 -topic_type: +topic_type: - "apiref" --- # ICLRValidator Interface -Provides methods for validating portable executable (PE) images and reporting validation errors. - -## Methods - -|Method|Description| -|------------|-----------------| -|[FormatEventInfo Method](iclrvalidator-formateventinfo-method.md)|Gets a detailed message about the specified validation error.| -|[Validate Method](iclrvalidator-validate-method.md)|Validates the portable executable or Microsoft intermediate language (MSIL) in the specified file.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** IValidator.idl, IValidator.h - - **Library:** Included as a resource in MSCorEE.dll - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Provides methods for validating portable executable (PE) images and reporting validation errors. + +## Methods + +|Method|Description| +|------------|-----------------| +|[FormatEventInfo Method](iclrvalidator-formateventinfo-method.md)|Gets a detailed message about the specified validation error.| +|[Validate Method](iclrvalidator-validate-method.md)|Validates the portable executable or common intermediate language (CIL) in the specified file.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** IValidator.idl, IValidator.h + + **Library:** Included as a resource in MSCorEE.dll + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICLRErrorReportingManager Interface](iclrerrorreportingmanager-interface.md) diff --git a/docs/framework/unmanaged-api/hosting/iclrvalidator-validate-method.md b/docs/framework/unmanaged-api/hosting/iclrvalidator-validate-method.md index 5b1fa3ead2c39..0ac6dd1afc64b 100644 --- a/docs/framework/unmanaged-api/hosting/iclrvalidator-validate-method.md +++ b/docs/framework/unmanaged-api/hosting/iclrvalidator-validate-method.md @@ -2,87 +2,87 @@ description: "Learn more about: ICLRValidator::Validate Method" title: "ICLRValidator::Validate Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICLRValidator.Validate" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICLRValidator::Validate" -helpviewer_keywords: +helpviewer_keywords: - "Validate method, ICLRValidator interface [.NET Framework hosting]" - "ICLRValidator::Validate method [.NET Framework hosting]" ms.assetid: 0b1b432a-d234-4002-839b-81366c3a8bdc -topic_type: +topic_type: - "apiref" --- # ICLRValidator::Validate Method -Validates the portable executable (PE) or Microsoft intermediate language (MSIL) in the specified file. - -## Syntax - -```cpp -HRESULT Validate ( - [in] IVEHandler *veh, - [in] unsigned long ulAppDomainId, - [in] unsigned long ulFlags, - [in] unsigned long ulMaxError, - [in] unsigned long token, - [in] LPWSTR fileName, - [in, size_is(ulSize)] BYTE *pe, - [in] unsigned long ulSize +Validates the portable executable (PE) or common intermediate language (CIL) in the specified file. + +## Syntax + +```cpp +HRESULT Validate ( + [in] IVEHandler *veh, + [in] unsigned long ulAppDomainId, + [in] unsigned long ulFlags, + [in] unsigned long ulMaxError, + [in] unsigned long token, + [in] LPWSTR fileName, + [in, size_is(ulSize)] BYTE *pe, + [in] unsigned long ulSize ); -``` - -## Parameters - - `veh` - [in] A pointer to an `IVEHandler` instance that handles validation errors. - - `ulAppDomainId` - [in] The identifier for the current . - - `ulFlags` - [in] A combination of [ValidatorFlags](validatorflags-enumeration.md) values, indicating the kind of validation that should be performed. - - `ulMaxError` - [in] The maximum number of errors to allow before exiting the validation. - - `token` - [in] Unused. - - `fileName` - [in] The name of the file to be validated. - - `pe` - [in] A pointer to the file buffer. - - `ulSize` - [in] The size, in bytes, of the file to be validated. - -## Return Value - -|HRESULT|Description| -|-------------|-----------------| -|S_OK|`Validate` returned successfully.| -|HOST_E_CLRNOTAVAILABLE|The common language runtime (CLR) has not been loaded into a process, or the CLR is in a state in which it cannot run managed code or process the call successfully.| -|HOST_E_TIMEOUT|The call timed out.| -|HOST_E_NOT_OWNER|The caller does not own the lock.| -|HOST_E_ABANDONED|An event was canceled while a blocked thread or fiber was waiting on it.| -|E_FAIL|An unknown catastrophic failure occurred. When a method returns E_FAIL, the CLR is no longer usable within the process. Subsequent calls to hosting methods return HOST_E_CLRNOTAVAILABLE.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** IValidator.idl, IValidator.h - - **Library:** Included as a resource in MSCorEE.dll - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +``` + +## Parameters + + `veh` + [in] A pointer to an `IVEHandler` instance that handles validation errors. + + `ulAppDomainId` + [in] The identifier for the current . + + `ulFlags` + [in] A combination of [ValidatorFlags](validatorflags-enumeration.md) values, indicating the kind of validation that should be performed. + + `ulMaxError` + [in] The maximum number of errors to allow before exiting the validation. + + `token` + [in] Unused. + + `fileName` + [in] The name of the file to be validated. + + `pe` + [in] A pointer to the file buffer. + + `ulSize` + [in] The size, in bytes, of the file to be validated. + +## Return Value + +|HRESULT|Description| +|-------------|-----------------| +|S_OK|`Validate` returned successfully.| +|HOST_E_CLRNOTAVAILABLE|The common language runtime (CLR) has not been loaded into a process, or the CLR is in a state in which it cannot run managed code or process the call successfully.| +|HOST_E_TIMEOUT|The call timed out.| +|HOST_E_NOT_OWNER|The caller does not own the lock.| +|HOST_E_ABANDONED|An event was canceled while a blocked thread or fiber was waiting on it.| +|E_FAIL|An unknown catastrophic failure occurred. When a method returns E_FAIL, the CLR is no longer usable within the process. Subsequent calls to hosting methods return HOST_E_CLRNOTAVAILABLE.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** IValidator.idl, IValidator.h + + **Library:** Included as a resource in MSCorEE.dll + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICLRValidator Interface](iclrvalidator-interface.md) diff --git a/docs/framework/unmanaged-api/hosting/ivalidator-interface.md b/docs/framework/unmanaged-api/hosting/ivalidator-interface.md index 1f1d55cc9a195..07404ee94ddd6 100644 --- a/docs/framework/unmanaged-api/hosting/ivalidator-interface.md +++ b/docs/framework/unmanaged-api/hosting/ivalidator-interface.md @@ -2,41 +2,41 @@ description: "Learn more about: IValidator Interface" title: "IValidator Interface" ms.date: "03/30/2017" -api_name: +api_name: - "IValidator" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "IValidator" -helpviewer_keywords: +helpviewer_keywords: - "IValidator interface [.NET Framework hosting]" ms.assetid: b297e3b0-20f9-478f-b707-5e2eecb2b5b2 -topic_type: +topic_type: - "apiref" --- # IValidator Interface -Provides methods for validating portable executable (PE) images and reporting validation errors. - -## Methods - -|Method|Description| -|------------|-----------------| -|Validate|Validates the specified PE or Microsoft intermediate language (MSIL) file.| -|FormatEventInfo|Gets the error message corresponding to the specified validation error.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** IValidator.idl, IValidator.h - - **Library:** Included as a resource in MSCorEE.dll - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Provides methods for validating portable executable (PE) images and reporting validation errors. + +## Methods + +|Method|Description| +|------------|-----------------| +|Validate|Validates the specified PE or common intermediate language (CIL) file.| +|FormatEventInfo|Gets the error message corresponding to the specified validation error.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** IValidator.idl, IValidator.h + + **Library:** Included as a resource in MSCorEE.dll + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [Hosting Interfaces](hosting-interfaces.md) diff --git a/docs/framework/unmanaged-api/hosting/ivalidator-validate-method.md b/docs/framework/unmanaged-api/hosting/ivalidator-validate-method.md index 866bb4eb3d30e..f98a917cdb9c9 100644 --- a/docs/framework/unmanaged-api/hosting/ivalidator-validate-method.md +++ b/docs/framework/unmanaged-api/hosting/ivalidator-validate-method.md @@ -2,72 +2,72 @@ description: "Learn more about: IValidator::Validate Method" title: "IValidator::Validate Method" ms.date: "03/30/2017" -api_name: +api_name: - "IValidator.Validate" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "Validate" -helpviewer_keywords: +helpviewer_keywords: - "IValidator::Validate method [.NET Framework hosting]" - "Validate method, IValidator interface [.NET Framework hosting]" ms.assetid: 7d68666a-fb73-4455-bebd-908d49a16abc -topic_type: +topic_type: - "apiref" --- # IValidator::Validate Method -Validates the specified portable executable (PE) or Microsoft intermediate language (MSIL) file. - -## Syntax - -```cpp -HRESULT Validate ( - [in] IVEHandler *veh, - [in] IUnknown *pAppDomain, - [in] unsigned long ulFlags, - [in] unsigned long ulMaxError, - [in] unsigned long token, - [in] LPWSTR fileName, - [in, size_is(ulSize)] BYTE *pe, - [in] unsigned long ulSize -); -``` - -## Parameters - - `veh` - [in] A pointer to an `IVEHandler` instance that handles validation errors. - - `pAppDomain` - [in] A pointer to the application domain in which the file is loaded. - - `ulFlags` - [in] A bitwise combination of [ValidatorFlags](validatorflags-enumeration.md) values, indicating the validations that should be performed. - - `ulMaxError` - [in] The maximum number of errors to allow before exiting the validation. - - `token` - [in] Not used. - - `fileName` - [in] A string that specifies the name of the file to be validated. - - `pe` - [in] A pointer to the memory buffer in which the file is stored. - - `ulSize` - [in] The size, in bytes, of the file to be validated. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** IValidator.idl, IValidator.h - - **Library:** Included as a resource in MSCorEE.dll - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] +Validates the specified portable executable (PE) or common intermediate language (CIL) file. + +## Syntax + +```cpp +HRESULT Validate ( + [in] IVEHandler *veh, + [in] IUnknown *pAppDomain, + [in] unsigned long ulFlags, + [in] unsigned long ulMaxError, + [in] unsigned long token, + [in] LPWSTR fileName, + [in, size_is(ulSize)] BYTE *pe, + [in] unsigned long ulSize +); +``` + +## Parameters + + `veh` + [in] A pointer to an `IVEHandler` instance that handles validation errors. + + `pAppDomain` + [in] A pointer to the application domain in which the file is loaded. + + `ulFlags` + [in] A bitwise combination of [ValidatorFlags](validatorflags-enumeration.md) values, indicating the validations that should be performed. + + `ulMaxError` + [in] The maximum number of errors to allow before exiting the validation. + + `token` + [in] Not used. + + `fileName` + [in] A string that specifies the name of the file to be validated. + + `pe` + [in] A pointer to the memory buffer in which the file is stored. + + `ulSize` + [in] The size, in bytes, of the file to be validated. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** IValidator.idl, IValidator.h + + **Library:** Included as a resource in MSCorEE.dll + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] diff --git a/docs/framework/unmanaged-api/hosting/validatorflags-enumeration.md b/docs/framework/unmanaged-api/hosting/validatorflags-enumeration.md index 77c3f7f79436c..581dc0f4e5841 100644 --- a/docs/framework/unmanaged-api/hosting/validatorflags-enumeration.md +++ b/docs/framework/unmanaged-api/hosting/validatorflags-enumeration.md @@ -2,56 +2,56 @@ description: "Learn more about: ValidatorFlags Enumeration" title: "ValidatorFlags Enumeration" ms.date: "03/30/2017" -api_name: +api_name: - "ValidatorFlags" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ValidatorFlags" -helpviewer_keywords: +helpviewer_keywords: - "ValidatorFlags enumeration [.NET Framework hosting]" ms.assetid: a3f5c266-3fcc-4ad1-aaf5-4cdbe26304ad -topic_type: +topic_type: - "apiref" --- # ValidatorFlags Enumeration -Contains values that indicate the type of validation that should be performed in a call to the [ICLRValidator::Validate](iclrvalidator-validate-method.md) method. - -## Syntax - -```cpp -enum ValidatorFlags { - VALIDATOR_EXTRA_VERBOSE = 0x00000001, - VALIDATOR_SHOW_SOURCE_LINES = 0x00000002, - VALIDATOR_CHECK_ILONLY = 0x00000004, - VALIDATOR_CHECK_PEFORMAT_ONLY = 0x00000008, - VALIDATOR_NOCHECK_PEFORMAT = 0x00000010, -}; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`VALIDATOR_CHECK_ILONLY`|Specifies that only the Microsoft intermediate language (MSIL) in the executable file should be validated.| -|`VALIDATOR_CHECK_PEFORMAT_ONLY`|Specifies that only the format of the executable file should be validated.| -|`VALIDATOR_EXTRA_VERBOSE`|Specifies that all types of validation should be performed and reported on.| -|`VALIDATOR_NOCHECK_PEFORMAT`|Specifies that the format of the executable file should not be validated.| -|`VALIDATOR_SHOW_SOURCE_LINES`|Specifies that validation error messages should include the lines of source code that raise validation errors. This field value is not valid in .NET Framework version 2.0.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** IValidator.idl, IValidator.h - - **Library:** MSCorEE.dll - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Contains values that indicate the type of validation that should be performed in a call to the [ICLRValidator::Validate](iclrvalidator-validate-method.md) method. + +## Syntax + +```cpp +enum ValidatorFlags { + VALIDATOR_EXTRA_VERBOSE = 0x00000001, + VALIDATOR_SHOW_SOURCE_LINES = 0x00000002, + VALIDATOR_CHECK_ILONLY = 0x00000004, + VALIDATOR_CHECK_PEFORMAT_ONLY = 0x00000008, + VALIDATOR_NOCHECK_PEFORMAT = 0x00000010, +}; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`VALIDATOR_CHECK_ILONLY`|Specifies that only the common intermediate language (CIL) in the executable file should be validated.| +|`VALIDATOR_CHECK_PEFORMAT_ONLY`|Specifies that only the format of the executable file should be validated.| +|`VALIDATOR_EXTRA_VERBOSE`|Specifies that all types of validation should be performed and reported on.| +|`VALIDATOR_NOCHECK_PEFORMAT`|Specifies that the format of the executable file should not be validated.| +|`VALIDATOR_SHOW_SOURCE_LINES`|Specifies that validation error messages should include the lines of source code that raise validation errors. This field value is not valid in .NET Framework version 2.0.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** IValidator.idl, IValidator.h + + **Library:** MSCorEE.dll + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICLRErrorReportingManager Interface](iclrerrorreportingmanager-interface.md) diff --git a/docs/framework/unmanaged-api/metadata/cormethodimpl-enumeration.md b/docs/framework/unmanaged-api/metadata/cormethodimpl-enumeration.md index 58dec4d774f1c..f487cd450ac27 100644 --- a/docs/framework/unmanaged-api/metadata/cormethodimpl-enumeration.md +++ b/docs/framework/unmanaged-api/metadata/cormethodimpl-enumeration.md @@ -2,81 +2,81 @@ description: "Learn more about: CorMethodImpl Enumeration" title: "CorMethodImpl Enumeration" ms.date: "03/30/2017" -api_name: +api_name: - "CorMethodImpl" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "CorMethodImpl" -helpviewer_keywords: +helpviewer_keywords: - "CorMethodImpl enumeration [.NET Framework metadata]" ms.assetid: ffbb3caf-20da-4a4b-8983-77376e72b990 -topic_type: +topic_type: - "apiref" --- # CorMethodImpl Enumeration -Contains values that describe method implementation features. - -## Syntax - -```cpp -typedef enum CorMethodImpl { - - miCodeTypeMask = 0x0003, - miIL = 0x0000, - miNative = 0x0001, - miOPTIL = 0x0002, - miRuntime = 0x0003, - - miManagedMask = 0x0004, - miUnmanaged = 0x0004, - miManaged = 0x0000, - - miForwardRef = 0x0010, - miPreserveSig = 0x0080, - - miInternalCall = 0x1000, - miSynchronized = 0x0020, - miNoInlining = 0x0008, - miAggressiveInlining = 0x0100, - miNoOptimization = 0x0040, - miMaxMethodImplVal = 0xffff - -} CorMethodImpl; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`miCodeTypeMask`|Flags that describe code type.| -|`miIL`|Specifies that the method implementation is Microsoft intermediate language (MSIL).| -|`miNative`|Specifies that the method implementation is native.| -|`miOPTIL`|Specifies that the method implementation is OPTIL.| -|`miRuntime`|Specifies that the method implementation is provided by the common language runtime.| -|`miManagedMask`|Flags that indicate whether the code is managed or unmanaged.| -|`miUnmanaged`|Specifies that the method implementation is unmanaged.| -|`miManaged`|Specifies that the method implementation is managed.| -|`miForwardRef`|Specifies that the method is defined. This flag is used primarily in merge scenarios.| -|`miPreserveSig`|Specifies that the method signature cannot be mangled for an HRESULT conversion.| -|`miInternalCall`|Reserved for internal use by the common language runtime.| -|`miSynchronized`|Specifies that the method is single-threaded through its body.| -|`miNoInlining`|Specifies that the method cannot be inlined.| -|`miAggressiveInlining`|Specifies that the method should be inlined if possible.| -|`miNoOptimization`|Specifies that the method should not be optimized.| -|`miMaxMethodImplVal`|The maximum valid value for a `CorMethodImpl`.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorHdr.h - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +Contains values that describe method implementation features. + +## Syntax + +```cpp +typedef enum CorMethodImpl { + + miCodeTypeMask = 0x0003, + miIL = 0x0000, + miNative = 0x0001, + miOPTIL = 0x0002, + miRuntime = 0x0003, + + miManagedMask = 0x0004, + miUnmanaged = 0x0004, + miManaged = 0x0000, + + miForwardRef = 0x0010, + miPreserveSig = 0x0080, + + miInternalCall = 0x1000, + miSynchronized = 0x0020, + miNoInlining = 0x0008, + miAggressiveInlining = 0x0100, + miNoOptimization = 0x0040, + miMaxMethodImplVal = 0xffff + +} CorMethodImpl; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`miCodeTypeMask`|Flags that describe code type.| +|`miIL`|Specifies that the method implementation is common intermediate language (CIL).| +|`miNative`|Specifies that the method implementation is native.| +|`miOPTIL`|Specifies that the method implementation is OPTIL.| +|`miRuntime`|Specifies that the method implementation is provided by the common language runtime.| +|`miManagedMask`|Flags that indicate whether the code is managed or unmanaged.| +|`miUnmanaged`|Specifies that the method implementation is unmanaged.| +|`miManaged`|Specifies that the method implementation is managed.| +|`miForwardRef`|Specifies that the method is defined. This flag is used primarily in merge scenarios.| +|`miPreserveSig`|Specifies that the method signature cannot be mangled for an HRESULT conversion.| +|`miInternalCall`|Reserved for internal use by the common language runtime.| +|`miSynchronized`|Specifies that the method is single-threaded through its body.| +|`miNoInlining`|Specifies that the method cannot be inlined.| +|`miAggressiveInlining`|Specifies that the method should be inlined if possible.| +|`miNoOptimization`|Specifies that the method should not be optimized.| +|`miMaxMethodImplVal`|The maximum valid value for a `CorMethodImpl`.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorHdr.h + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [Metadata Enumerations](metadata-enumerations.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilercallback-jitcompilationstarted-method.md b/docs/framework/unmanaged-api/profiling/icorprofilercallback-jitcompilationstarted-method.md index 31865933f695c..01aeafe799197 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilercallback-jitcompilationstarted-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilercallback-jitcompilationstarted-method.md @@ -2,59 +2,59 @@ description: "Learn more about: ICorProfilerCallback::JITCompilationStarted Method" title: "ICorProfilerCallback::JITCompilationStarted Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerCallback.JITCompilationStarted" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerCallback::JITCompilationStarted" -helpviewer_keywords: +helpviewer_keywords: - "JITCompilationStarted method [.NET Framework profiling]" - "ICorProfilerCallback::JITCompilationStarted method [.NET Framework profiling]" ms.assetid: 31782b36-d311-4518-8f45-25f65385af5b -topic_type: +topic_type: - "apiref" --- # ICorProfilerCallback::JITCompilationStarted Method -Notifies the profiler that the just-in-time (JIT) compiler has started to compile a function. - -## Syntax - -```cpp -HRESULT JITCompilationStarted( - [in] FunctionID functionId, - [in] BOOL fIsSafeToBlock); -``` - -## Parameters - - `functionId` - [in] The ID of the function for which the compilation is starting. - - `fIsSafeToBlock` - [in] A value indicating to the profiler whether blocking will affect the operation of the runtime. The value is `true` if blocking may cause the runtime to wait for the calling thread to return from this callback; otherwise, `false`. - - Although a value of `true` will not harm the runtime, it can skew the profiling results. - -## Remarks - - It is possible to receive more than one pair of `JITCompilationStarted` and [ICorProfilerCallback::JITCompilationFinished](icorprofilercallback-jitcompilationfinished-method.md) calls for each function because of the way the runtime handles class constructors. For example, the runtime starts to JIT-compile method A, but the class constructor for class B needs to be run. Therefore, the runtime JIT-compiles the constructor for class B and runs it. While the constructor is running, it makes a call to method A, which causes method A to be JIT-compiled again. In this scenario, the first JIT compilation of method A is halted. However, both attempts to JIT-compile method A are reported with JIT-compilation events. If the profiler is going to replace Microsoft intermediate language (MSIL) code for method A by calling the [ICorProfilerInfo::SetILFunctionBody](icorprofilerinfo-setilfunctionbody-method.md) method, it must do so for both `JITCompilationStarted` events, but it may use the same MSIL block for both. - - Profilers must support the sequence of JIT callbacks in cases where two threads are simultaneously making callbacks. For example, thread A calls `JITCompilationStarted`. However, before thread A calls `JITCompilationFinished`, thread B calls [ICorProfilerCallback::ExceptionSearchFunctionEnter](icorprofilercallback-exceptionsearchfunctionenter-method.md) with the function ID from thread A's `JITCompilationStarted` callback. It might appear that the function ID should not yet be valid because a call to `JITCompilationFinished` had not yet been received by the profiler. However, in a case like this one, the function ID is valid. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Notifies the profiler that the just-in-time (JIT) compiler has started to compile a function. + +## Syntax + +```cpp +HRESULT JITCompilationStarted( + [in] FunctionID functionId, + [in] BOOL fIsSafeToBlock); +``` + +## Parameters + + `functionId` + [in] The ID of the function for which the compilation is starting. + + `fIsSafeToBlock` + [in] A value indicating to the profiler whether blocking will affect the operation of the runtime. The value is `true` if blocking may cause the runtime to wait for the calling thread to return from this callback; otherwise, `false`. + + Although a value of `true` will not harm the runtime, it can skew the profiling results. + +## Remarks + + It is possible to receive more than one pair of `JITCompilationStarted` and [ICorProfilerCallback::JITCompilationFinished](icorprofilercallback-jitcompilationfinished-method.md) calls for each function because of the way the runtime handles class constructors. For example, the runtime starts to JIT-compile method A, but the class constructor for class B needs to be run. Therefore, the runtime JIT-compiles the constructor for class B and runs it. While the constructor is running, it makes a call to method A, which causes method A to be JIT-compiled again. In this scenario, the first JIT compilation of method A is halted. However, both attempts to JIT-compile method A are reported with JIT-compilation events. If the profiler is going to replace common intermediate language (CIL) code for method A by calling the [ICorProfilerInfo::SetILFunctionBody](icorprofilerinfo-setilfunctionbody-method.md) method, it must do so for both `JITCompilationStarted` events, but it may use the same CIL block for both. + + Profilers must support the sequence of JIT callbacks in cases where two threads are simultaneously making callbacks. For example, thread A calls `JITCompilationStarted`. However, before thread A calls `JITCompilationFinished`, thread B calls [ICorProfilerCallback::ExceptionSearchFunctionEnter](icorprofilercallback-exceptionsearchfunctionenter-method.md) with the function ID from thread A's `JITCompilationStarted` callback. It might appear that the function ID should not yet be valid because a call to `JITCompilationFinished` had not yet been received by the profiler. However, in a case like this one, the function ID is valid. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorProfilerCallback Interface](icorprofilercallback-interface.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbody-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbody-method.md index 7eb2b0548e21b..6e5c31af7edbb 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbody-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbody-method.md @@ -2,65 +2,65 @@ description: "Learn more about: ICorProfilerInfo::GetILFunctionBody Method" title: "ICorProfilerInfo::GetILFunctionBody Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo.GetILFunctionBody" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo::GetILFunctionBody" -helpviewer_keywords: +helpviewer_keywords: - "GetILFunctionBody method [.NET Framework profiling]" - "ICorProfilerInfo::GetILFunctionBody method [.NET Framework profiling]" ms.assetid: e29b46bc-5fdc-4894-b0c2-619df4b65ded -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo::GetILFunctionBody Method -Gets a pointer to the body of a method in Microsoft intermediate language (MSIL) code, starting at its header. - -## Syntax - -```cpp -HRESULT GetILFunctionBody( - [in] ModuleID moduleId, - [in] mdMethodDef methodId, - [out] LPCBYTE *ppMethodHeader, - [out] ULONG *pcbMethodSize); -``` - -## Parameters - - `moduleId` - [in] The ID of the module in which the function resides. - - `methodId` - [in] The metadata token for the method. - - `ppMethodHeader` - [out] A pointer to the method's header. - - `pcbMethodSize` - [out] An integer that specifies the size of the method. - -## Remarks - - A method is scoped by the module in which it lives. Because the `GetILFunctionBody` method is designed to give a tool access to the MSIL code before it has been loaded by the common language runtime (CLR), it uses the metadata token of the method to find the desired instance. - - `GetILFunctionBody` can return a CORPROF_E_FUNCTION_NOT_IL HRESULT if the `methodId` points to a method without any MSIL code (such as an abstract method, or a platform invoke (PInvoke) method). - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Gets a pointer to the body of a method in common intermediate language (CIL) code, starting at its header. + +## Syntax + +```cpp +HRESULT GetILFunctionBody( + [in] ModuleID moduleId, + [in] mdMethodDef methodId, + [out] LPCBYTE *ppMethodHeader, + [out] ULONG *pcbMethodSize); +``` + +## Parameters + + `moduleId` + [in] The ID of the module in which the function resides. + + `methodId` + [in] The metadata token for the method. + + `ppMethodHeader` + [out] A pointer to the method's header. + + `pcbMethodSize` + [out] An integer that specifies the size of the method. + +## Remarks + + A method is scoped by the module in which it lives. Because the `GetILFunctionBody` method is designed to give a tool access to the CIL code before it has been loaded by the common language runtime (CLR), it uses the metadata token of the method to find the desired instance. + + `GetILFunctionBody` can return a CORPROF_E_FUNCTION_NOT_IL HRESULT if the `methodId` points to a method without any CIL code (such as an abstract method, or a platform invoke (PInvoke) method). + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorProfilerInfo Interface](icorprofilerinfo-interface.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbodyallocator-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbodyallocator-method.md index c893db23593a2..1026889ea52bc 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbodyallocator-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbodyallocator-method.md @@ -2,55 +2,55 @@ description: "Learn more about: ICorProfilerInfo::GetILFunctionBodyAllocator Method" title: "ICorProfilerInfo::GetILFunctionBodyAllocator Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo.GetILFunctionBodyAllocator" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo::GetILFunctionBodyAllocator" -helpviewer_keywords: +helpviewer_keywords: - "GetILFunctionBodyAllocator method [.NET Framework profiling]" - "ICorProfilerInfo::GetILFunctionBodyAllocator method [.NET Framework profiling]" ms.assetid: 5da1bf3d-dddf-4892-b266-578ee54d570b -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo::GetILFunctionBodyAllocator Method -Gets an interface that provides a method to allocate memory to be used for swapping out the body of a method in Microsoft intermediate language (MSIL) code. - -## Syntax - -```cpp -HRESULT GetILFunctionBodyAllocator( - [in] ModuleID moduleId, - [out] IMethodMalloc **ppMalloc); -``` - -## Parameters - - `moduleId` - [in] The ID of the module in which the method resides. - - `ppMalloc` - [out] A pointer to an [IMethodMalloc](imethodmalloc-interface.md) interface that provides a method to allocate the memory. - -## Remarks - - A method body in MSIL code must be located as a relative virtual address (RVA), relative to the loaded module, which means that it follows the module within 4 GB. To make it easier for a tool to swap out the body of a method, the `GetILFunctionBodyAllocator` method ensures that memory is allocated within that range. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Gets an interface that provides a method to allocate memory to be used for swapping out the body of a method in common intermediate language (CIL) code. + +## Syntax + +```cpp +HRESULT GetILFunctionBodyAllocator( + [in] ModuleID moduleId, + [out] IMethodMalloc **ppMalloc); +``` + +## Parameters + + `moduleId` + [in] The ID of the module in which the method resides. + + `ppMalloc` + [out] A pointer to an [IMethodMalloc](imethodmalloc-interface.md) interface that provides a method to allocate the memory. + +## Remarks + + A method body in CIL code must be located as a relative virtual address (RVA), relative to the loaded module, which means that it follows the module within 4 GB. To make it easier for a tool to swap out the body of a method, the `GetILFunctionBodyAllocator` method ensures that memory is allocated within that range. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorProfilerInfo Interface](icorprofilerinfo-interface.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getiltonativemapping-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getiltonativemapping-method.md index 9850bef327436..4959b3ec491da 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getiltonativemapping-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getiltonativemapping-method.md @@ -2,68 +2,68 @@ description: "Learn more about: ICorProfilerInfo::GetILToNativeMapping Method" title: "ICorProfilerInfo::GetILToNativeMapping Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo.GetILToNativeMapping" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo::GetILToNativeMapping" -helpviewer_keywords: +helpviewer_keywords: - "GetILToNativeMapping method, ICorProfilerInfo interface [.NET Framework profiling]" - "ICorProfilerInfo::GetILToNativeMapping method [.NET Framework profiling]" ms.assetid: 6a5431ef-22fb-4e53-bac5-703986297eb1 -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo::GetILToNativeMapping Method -Gets a map from Microsoft intermediate language (MSIL) offsets to native offsets for the code contained in the specified function. - -## Syntax - -```cpp -HRESULT GetILToNativeMapping( - [in] FunctionID functionId, - [in] ULONG32 cMap, - [out] ULONG32 *pcMap, - [out, size_is(cMap), length_is(*pcMap)] - COR_DEBUG_IL_TO_NATIVE_MAP map[]); -``` - -## Parameters - - `functionId` - [in] The ID of the function that contains the code. - - `cMap` - [in] The maximum size of the `map` array. - - `pcMap` - [out] The total number of available COR_DEBUG_IL_TO_NATIVE_MAP structures. - - `map` - [out] An array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures, each of which specifies the offsets. After the `GetILToNativeMapping` method returns, `map` will contain some or all of the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. - -## Remarks - - The `GetILToNativeMapping` method returns an array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To convey that certain ranges of native instructions correspond to special regions of code (for example, the prolog), an entry in the array can have its `ilOffset` field set to a value of the [CorDebugIlToNativeMappingTypes](../debugging/cordebugiltonativemappingtypes-enumeration.md) enumeration. - - After `GetILToNativeMapping` returns, you must verify that the `map` buffer was large enough to contain all the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To do this, compare the value of `cMap` with the value of the `pcMap` parameter. If the `pcMap` value, when it is multiplied by the size of a `COR_DEBUG_IL_TO_NATIVE_MAP` structure, is larger than `cMap`, allocate a larger `map` buffer, update `cMap` with the new, larger size, and call `GetILToNativeMapping` again. - - Alternatively, you can first call `GetILToNativeMapping` with a zero-length `map` buffer to obtain the correct buffer size. You can then set the buffer size to the value returned in `pcMap` and call `GetILToNativeMapping` again. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Gets a map from common intermediate language (CIL) offsets to native offsets for the code contained in the specified function. + +## Syntax + +```cpp +HRESULT GetILToNativeMapping( + [in] FunctionID functionId, + [in] ULONG32 cMap, + [out] ULONG32 *pcMap, + [out, size_is(cMap), length_is(*pcMap)] + COR_DEBUG_IL_TO_NATIVE_MAP map[]); +``` + +## Parameters + + `functionId` + [in] The ID of the function that contains the code. + + `cMap` + [in] The maximum size of the `map` array. + + `pcMap` + [out] The total number of available COR_DEBUG_IL_TO_NATIVE_MAP structures. + + `map` + [out] An array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures, each of which specifies the offsets. After the `GetILToNativeMapping` method returns, `map` will contain some or all of the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. + +## Remarks + + The `GetILToNativeMapping` method returns an array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To convey that certain ranges of native instructions correspond to special regions of code (for example, the prolog), an entry in the array can have its `ilOffset` field set to a value of the [CorDebugIlToNativeMappingTypes](../debugging/cordebugiltonativemappingtypes-enumeration.md) enumeration. + + After `GetILToNativeMapping` returns, you must verify that the `map` buffer was large enough to contain all the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To do this, compare the value of `cMap` with the value of the `pcMap` parameter. If the `pcMap` value, when it is multiplied by the size of a `COR_DEBUG_IL_TO_NATIVE_MAP` structure, is larger than `cMap`, allocate a larger `map` buffer, update `cMap` with the new, larger size, and call `GetILToNativeMapping` again. + + Alternatively, you can first call `GetILToNativeMapping` with a zero-length `map` buffer to obtain the correct buffer size. You can then set the buffer size to the value returned in `pcMap` and call `GetILToNativeMapping` again. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorProfilerInfo Interface](icorprofilerinfo-interface.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-interface.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-interface.md index 423dd4f3d6288..1d6e6e726cb19 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-interface.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-interface.md @@ -2,83 +2,83 @@ description: "Learn more about: ICorProfilerInfo Interface" title: "ICorProfilerInfo Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo" -helpviewer_keywords: +helpviewer_keywords: - "ICorProfilerInfo interface [.NET Framework profiling]" ms.assetid: eb4e4ce0-06e7-4469-bbc4-edc2eb5da4b1 -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo Interface -Provides methods for use by code profilers to communicate with the common language runtime (CLR) to control event monitoring and request information. - +Provides methods for use by code profilers to communicate with the common language runtime (CLR) to control event monitoring and request information. + > [!NOTE] -> Each method in the `ICorProfilerInfo` interface returns an HRESULT to indicate success or failure. See CorError.h for a list of possible return codes. - -## Methods - -|Method|Description| -|------------|-----------------| -|[BeginInprocDebugging Method](icorprofilerinfo-begininprocdebugging-method.md)|Initializes in-process debugging support. This method is obsolete in .NET Framework version 2.0.| -|[EndInprocDebugging Method](icorprofilerinfo-endinprocdebugging-method.md)|Shuts down an in-process debugging session. This method is obsolete in .NET Framework version 2.0.| -|[ForceGC Method](icorprofilerinfo-forcegc-method.md)|Forces garbage collection to occur within the runtime.| -|[GetAppDomainInfo Method](icorprofilerinfo-getappdomaininfo-method.md)|Gets information about the specified application domain.| -|[GetAssemblyInfo Method](icorprofilerinfo-getassemblyinfo-method.md)|Gets information about the specified assembly.| -|[GetClassFromObject Method](icorprofilerinfo-getclassfromobject-method.md)|Gets the `ClassID` of an

object, given its `ObjectID`.| -|[GetClassFromToken Method](icorprofilerinfo-getclassfromtoken-method.md)|Gets the ID of the class, given the metadata token. This method is obsolete in .NET Framework version 2.0. Use the [ICorProfilerInfo2::GetClassFromTokenAndTypeArgs](icorprofilerinfo2-getclassfromtokenandtypeargs-method.md) method instead.| -|[GetClassIDInfo Method](icorprofilerinfo-getclassidinfo-method.md)|Gets the parent module and the metadata token for the specified class.| -|[GetCodeInfo Method](icorprofilerinfo-getcodeinfo-method.md)|Gets the extent of native code associated with the specified function ID. This method is obsolete. Use the [ICorProfilerInfo2::GetCodeInfo2](icorprofilerinfo2-getcodeinfo2-method.md) method instead.| -|[GetCurrentThreadID Method](icorprofilerinfo-getcurrentthreadid-method.md)|Gets the ID of the current thread, if it is a managed thread.| -|[GetEventMask Method](icorprofilerinfo-geteventmask-method.md)|Gets the current event categories for which the profiler wants to receive event notifications from the CLR.| -|[GetFunctionFromIP Method](icorprofilerinfo-getfunctionfromip-method.md)|Maps a managed code instruction pointer to a `FunctionID`.| -|[GetFunctionFromToken Method](icorprofilerinfo-getfunctionfromtoken-method.md)|Gets the ID of a function. This method is obsolete in .NET Framework version 2.0. Use the [ICorProfilerInfo2::GetFunctionFromTokenAndTypeArgs](icorprofilerinfo2-getfunctionfromtokenandtypeargs-method.md) method instead.| -|[GetFunctionInfo Method](icorprofilerinfo-getfunctioninfo-method.md)|Gets the parent class and metadata token for the specified function.| -|[GetHandleFromThread Method](icorprofilerinfo-gethandlefromthread-method.md)|Maps the ID of a thread to a Win32 thread handle.| -|[GetILFunctionBody Method](icorprofilerinfo-getilfunctionbody-method.md)|Gets a pointer to the body of a method in Microsoft intermediate language (MSIL) code, starting at its header.| -|[GetILFunctionBodyAllocator Method](icorprofilerinfo-getilfunctionbodyallocator-method.md)|Gets an interface that provides a method to allocate memory to be used for swapping out the body of a method in MSIL code.| -|[GetILToNativeMapping Method](icorprofilerinfo-getiltonativemapping-method.md)|Gets a map from MSIL offsets to native offsets for the code contained in the specified function.| -|[GetInprocInspectionInterface Method](icorprofilerinfo-getinprocinspectioninterface-method.md)|Gets an object that can be queried for an ICorDebugProcess interface. This method is obsolete in .NET Framework version 2.0.| -|[GetInprocInspectionIThisThread Method](icorprofilerinfo-getinprocinspectionithisthread-method.md)|Gets an object that can be queried for the ICorDebugThread interface. This method is obsolete in .NET Framework version 2.0.| -|[GetModuleInfo Method](icorprofilerinfo-getmoduleinfo-method.md)|Given a module ID, returns the file name of the module and the ID of the module's parent assembly.| -|[GetModuleMetaData Method](icorprofilerinfo-getmodulemetadata-method.md)|Gets a metadata interface instance that maps to the specified module.| -|[GetObjectSize Method](icorprofilerinfo-getobjectsize-method.md)|Gets the size of a specified object.| -|[GetThreadContext Method](icorprofilerinfo-getthreadcontext-method.md)|Gets the context identity currently associated with the specified thread.| -|[GetThreadInfo Method](icorprofilerinfo-getthreadinfo-method.md)|Gets the current Win32 thread identity for the specified thread.| -|[GetTokenAndMetadataFromFunction Method](icorprofilerinfo-gettokenandmetadatafromfunction-method.md)|Gets the metadata token and an instance of the metadata interface that can be used against the token for the specified function.| -|[IsArrayClass Method](icorprofilerinfo-isarrayclass-method.md)|Determines whether the specified class is an array class.| -|[SetEnterLeaveFunctionHooks Method](icorprofilerinfo-setenterleavefunctionhooks-method.md)|Specifies profiler-implemented functions to be called on "enter", "leave", and "tailcall" hooks of managed functions.| -|[SetEventMask Method](icorprofilerinfo-seteventmask-method.md)|Sets a value that specifies the types of events for which the profiler wants to receive notification from the CLR.| -|[SetFunctionIDMapper Method](icorprofilerinfo-setfunctionidmapper-method.md)|Specifies the profiler-implemented function that will be called to map `FunctionID` values to alternative values, which are passed to the profiler's function entry/exit hooks.| -|[SetFunctionReJIT Method](icorprofilerinfo-setfunctionrejit-method.md)|Not implemented. Do not use.| -|[SetILFunctionBody Method](icorprofilerinfo-setilfunctionbody-method.md)|Replaces the body of the specified function in the specified module.| -|[SetILInstrumentedCodeMap Method](icorprofilerinfo-setilinstrumentedcodemap-method.md)|Specifies how the offsets of a specified function's original MSIL map to the new offsets of the function's profiler-modified MSIL.| - -## Remarks +> Each method in the `ICorProfilerInfo` interface returns an HRESULT to indicate success or failure. See CorError.h for a list of possible return codes. + +## Methods + +|Method|Description| +|------------|-----------------| +|[BeginInprocDebugging Method](icorprofilerinfo-begininprocdebugging-method.md)|Initializes in-process debugging support. This method is obsolete in .NET Framework version 2.0.| +|[EndInprocDebugging Method](icorprofilerinfo-endinprocdebugging-method.md)|Shuts down an in-process debugging session. This method is obsolete in .NET Framework version 2.0.| +|[ForceGC Method](icorprofilerinfo-forcegc-method.md)|Forces garbage collection to occur within the runtime.| +|[GetAppDomainInfo Method](icorprofilerinfo-getappdomaininfo-method.md)|Gets information about the specified application domain.| +|[GetAssemblyInfo Method](icorprofilerinfo-getassemblyinfo-method.md)|Gets information about the specified assembly.| +|[GetClassFromObject Method](icorprofilerinfo-getclassfromobject-method.md)|Gets the `ClassID` of an

object, given its `ObjectID`.| +|[GetClassFromToken Method](icorprofilerinfo-getclassfromtoken-method.md)|Gets the ID of the class, given the metadata token. This method is obsolete in .NET Framework version 2.0. Use the [ICorProfilerInfo2::GetClassFromTokenAndTypeArgs](icorprofilerinfo2-getclassfromtokenandtypeargs-method.md) method instead.| +|[GetClassIDInfo Method](icorprofilerinfo-getclassidinfo-method.md)|Gets the parent module and the metadata token for the specified class.| +|[GetCodeInfo Method](icorprofilerinfo-getcodeinfo-method.md)|Gets the extent of native code associated with the specified function ID. This method is obsolete. Use the [ICorProfilerInfo2::GetCodeInfo2](icorprofilerinfo2-getcodeinfo2-method.md) method instead.| +|[GetCurrentThreadID Method](icorprofilerinfo-getcurrentthreadid-method.md)|Gets the ID of the current thread, if it is a managed thread.| +|[GetEventMask Method](icorprofilerinfo-geteventmask-method.md)|Gets the current event categories for which the profiler wants to receive event notifications from the CLR.| +|[GetFunctionFromIP Method](icorprofilerinfo-getfunctionfromip-method.md)|Maps a managed code instruction pointer to a `FunctionID`.| +|[GetFunctionFromToken Method](icorprofilerinfo-getfunctionfromtoken-method.md)|Gets the ID of a function. This method is obsolete in .NET Framework version 2.0. Use the [ICorProfilerInfo2::GetFunctionFromTokenAndTypeArgs](icorprofilerinfo2-getfunctionfromtokenandtypeargs-method.md) method instead.| +|[GetFunctionInfo Method](icorprofilerinfo-getfunctioninfo-method.md)|Gets the parent class and metadata token for the specified function.| +|[GetHandleFromThread Method](icorprofilerinfo-gethandlefromthread-method.md)|Maps the ID of a thread to a Win32 thread handle.| +|[GetILFunctionBody Method](icorprofilerinfo-getilfunctionbody-method.md)|Gets a pointer to the body of a method in common intermediate language (CIL) code, starting at its header.| +|[GetILFunctionBodyAllocator Method](icorprofilerinfo-getilfunctionbodyallocator-method.md)|Gets an interface that provides a method to allocate memory to be used for swapping out the body of a method in CIL code.| +|[GetILToNativeMapping Method](icorprofilerinfo-getiltonativemapping-method.md)|Gets a map from CIL offsets to native offsets for the code contained in the specified function.| +|[GetInprocInspectionInterface Method](icorprofilerinfo-getinprocinspectioninterface-method.md)|Gets an object that can be queried for an ICorDebugProcess interface. This method is obsolete in .NET Framework version 2.0.| +|[GetInprocInspectionIThisThread Method](icorprofilerinfo-getinprocinspectionithisthread-method.md)|Gets an object that can be queried for the ICorDebugThread interface. This method is obsolete in .NET Framework version 2.0.| +|[GetModuleInfo Method](icorprofilerinfo-getmoduleinfo-method.md)|Given a module ID, returns the file name of the module and the ID of the module's parent assembly.| +|[GetModuleMetaData Method](icorprofilerinfo-getmodulemetadata-method.md)|Gets a metadata interface instance that maps to the specified module.| +|[GetObjectSize Method](icorprofilerinfo-getobjectsize-method.md)|Gets the size of a specified object.| +|[GetThreadContext Method](icorprofilerinfo-getthreadcontext-method.md)|Gets the context identity currently associated with the specified thread.| +|[GetThreadInfo Method](icorprofilerinfo-getthreadinfo-method.md)|Gets the current Win32 thread identity for the specified thread.| +|[GetTokenAndMetadataFromFunction Method](icorprofilerinfo-gettokenandmetadatafromfunction-method.md)|Gets the metadata token and an instance of the metadata interface that can be used against the token for the specified function.| +|[IsArrayClass Method](icorprofilerinfo-isarrayclass-method.md)|Determines whether the specified class is an array class.| +|[SetEnterLeaveFunctionHooks Method](icorprofilerinfo-setenterleavefunctionhooks-method.md)|Specifies profiler-implemented functions to be called on "enter", "leave", and "tailcall" hooks of managed functions.| +|[SetEventMask Method](icorprofilerinfo-seteventmask-method.md)|Sets a value that specifies the types of events for which the profiler wants to receive notification from the CLR.| +|[SetFunctionIDMapper Method](icorprofilerinfo-setfunctionidmapper-method.md)|Specifies the profiler-implemented function that will be called to map `FunctionID` values to alternative values, which are passed to the profiler's function entry/exit hooks.| +|[SetFunctionReJIT Method](icorprofilerinfo-setfunctionrejit-method.md)|Not implemented. Do not use.| +|[SetILFunctionBody Method](icorprofilerinfo-setilfunctionbody-method.md)|Replaces the body of the specified function in the specified module.| +|[SetILInstrumentedCodeMap Method](icorprofilerinfo-setilinstrumentedcodemap-method.md)|Specifies how the offsets of a specified function's original CIL map to the new offsets of the function's profiler-modified CIL.| + +## Remarks + + A profiler calls a method in the `ICorProfilerInfo` interface to communicate with the CLR to control event monitoring and request information. + + The methods of the `ICorProfilerInfo` interface are implemented by the CLR using the free-threaded model. Each method returns an HRESULT to indicate success or failure. See CorError.h for a list of possible return codes. + + The CLR passes, via the profiler's implementation of [ICorProfilerCallback::Initialize](icorprofilercallback-initialize-method.md), an `ICorProfilerInfo` interface to each code profiler during initialization. A code profiler can then call methods of the `ICorProfilerInfo` interface to get information about managed code being executed under the control of the CLR. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib - A profiler calls a method in the `ICorProfilerInfo` interface to communicate with the CLR to control event monitoring and request information. - - The methods of the `ICorProfilerInfo` interface are implemented by the CLR using the free-threaded model. Each method returns an HRESULT to indicate success or failure. See CorError.h for a list of possible return codes. - - The CLR passes, via the profiler's implementation of [ICorProfilerCallback::Initialize](icorprofilercallback-initialize-method.md), an `ICorProfilerInfo` interface to each code profiler during initialization. A code profiler can then call methods of the `ICorProfilerInfo` interface to get information about managed code being executed under the control of the CLR. - -## Requirements + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - ## See also - [Profiling Interfaces](profiling-interfaces.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-setilinstrumentedcodemap-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-setilinstrumentedcodemap-method.md index 6e9b3c3997f83..c397a9ed8e786 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-setilinstrumentedcodemap-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-setilinstrumentedcodemap-method.md @@ -19,7 +19,7 @@ topic_type: --- # ICorProfilerInfo::SetILInstrumentedCodeMap Method -Sets a code map for the specified function using the specified Microsoft intermediate language (MSIL) map entries. +Sets a code map for the specified function using the specified common intermediate language (CIL) map entries. > [!NOTE] > In .NET Framework version 2.0, calling `SetILInstrumentedCodeMap` on a `FunctionID` that represents a generic function in a particular application domain will affect all instances of that function in the application domain. @@ -46,17 +46,17 @@ HRESULT SetILInstrumentedCodeMap( [in] The number of elements in the `cILMapEntries` array. `rgILMapEntries`\ -[in] An array of COR_IL_MAP structures, each of which specifies an MSIL offset. +[in] An array of COR_IL_MAP structures, each of which specifies a CIL offset. ## Remarks -A profiler often inserts statements within the source code of a method in order to instrument that method (for example, to notify when a given source line is reached). `SetILInstrumentedCodeMap` enables a profiler to map the original MSIL instructions to their new locations. A profiler can use the [ICorProfilerInfo::GetILToNativeMapping](icorprofilerinfo-getiltonativemapping-method.md) method to get the original MSIL offset for a given native offset. +A profiler often inserts statements within the source code of a method in order to instrument that method (for example, to notify when a given source line is reached). `SetILInstrumentedCodeMap` enables a profiler to map the original CIL instructions to their new locations. A profiler can use the [ICorProfilerInfo::GetILToNativeMapping](icorprofilerinfo-getiltonativemapping-method.md) method to get the original CIL offset for a given native offset. -The debugger will assume that each old offset refers to an MSIL offset within the original, unmodified MSIL code, and that each new offset refers to the MSIL offset within the new, instrumented code. The map should be sorted in increasing order. For stepping to work properly, follow these guidelines: +The debugger will assume that each old offset refers to a CIL offset within the original, unmodified CIL code, and that each new offset refers to the CIL offset within the new, instrumented code. The map should be sorted in increasing order. For stepping to work properly, follow these guidelines: -- Do not reorder instrumented MSIL code. +- Do not reorder instrumented CIL code. -- Do not remove the original MSIL code. +- Do not remove the original CIL code. - Include entries for all the sequence points from the program database (PDB) file in the map. The map does not interpolate missing entries. So, given the following map: diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo2-getcodeinfo2-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo2-getcodeinfo2-method.md index d719e39b0ed4a..d174477449488 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo2-getcodeinfo2-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo2-getcodeinfo2-method.md @@ -2,68 +2,68 @@ description: "Learn more about: ICorProfilerInfo2::GetCodeInfo2 Method" title: "ICorProfilerInfo2::GetCodeInfo2 Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo2.GetCodeInfo2" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo2::GetCodeInfo2" -helpviewer_keywords: +helpviewer_keywords: - "ICorProfilerInfo2::GetCodeInfo2 method [.NET Framework profiling]" - "GetCodeInfo2 method [.NET Framework profiling]" ms.assetid: 532da6ee-7f0a-401b-a61e-fc47ec235d2e -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo2::GetCodeInfo2 Method -Gets the extents of native code associated with the specified `FunctionID`. - -## Syntax - -```cpp -HRESULT GetCodeInfo2( - [in] FunctionID functionID, - [in] ULONG32 cCodeInfos, - [out] ULONG32 *pcCodeInfos, - [out, size_is(cCodeInfos), length_is(*pcCodeInfos)] - COR_PRF_CODE_INFO codeInfos[]); -``` - -## Parameters - - `functionID` - [in] The ID of the function with which the native code is associated. - - `cCodeInfos` - [in] The size of the `codeInfos` array. - - `pcCodeInfos` - [out] A pointer to the total number of [COR_PRF_CODE_INFO](cor-prf-code-info-structure.md) structures available. - - `codeInfos` - [out] A caller-provided buffer. After the method returns, it contains an array of `COR_PRF_CODE_INFO` structures, each of which describes a block of native code. - -## Remarks - - The extents are sorted in order of increasing Microsoft intermediate language (MSIL) offset. - - After `GetCodeInfo2` returns, you must verify that the `codeInfos` buffer was large enough to contain all the `COR_PRF_CODE_INFO` structures. To do this, compare the value of `cCodeInfos` with the value of the `cchName` parameter. If `cCodeInfos` divided by the size of a `COR_PRF_CODE_INFO` structure is smaller than `pcCodeInfos`, allocate a larger `codeInfos` buffer, update `cCodeInfos` with the new, larger size, and call `GetCodeInfo2` again. - - Alternatively, you can first call `GetCodeInfo2` with a zero-length `codeInfos` buffer to obtain the correct buffer size. You can then set the `codeInfos` buffer size to the value returned in `pcCodeInfos`, multiplied by the size of a `COR_PRF_CODE_INFO` structure, and call `GetCodeInfo2` again. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Gets the extents of native code associated with the specified `FunctionID`. + +## Syntax + +```cpp +HRESULT GetCodeInfo2( + [in] FunctionID functionID, + [in] ULONG32 cCodeInfos, + [out] ULONG32 *pcCodeInfos, + [out, size_is(cCodeInfos), length_is(*pcCodeInfos)] + COR_PRF_CODE_INFO codeInfos[]); +``` + +## Parameters + + `functionID` + [in] The ID of the function with which the native code is associated. + + `cCodeInfos` + [in] The size of the `codeInfos` array. + + `pcCodeInfos` + [out] A pointer to the total number of [COR_PRF_CODE_INFO](cor-prf-code-info-structure.md) structures available. + + `codeInfos` + [out] A caller-provided buffer. After the method returns, it contains an array of `COR_PRF_CODE_INFO` structures, each of which describes a block of native code. + +## Remarks + + The extents are sorted in order of increasing common intermediate language (CIL) offset. + + After `GetCodeInfo2` returns, you must verify that the `codeInfos` buffer was large enough to contain all the `COR_PRF_CODE_INFO` structures. To do this, compare the value of `cCodeInfos` with the value of the `cchName` parameter. If `cCodeInfos` divided by the size of a `COR_PRF_CODE_INFO` structure is smaller than `pcCodeInfos`, allocate a larger `codeInfos` buffer, update `cCodeInfos` with the new, larger size, and call `GetCodeInfo2` again. + + Alternatively, you can first call `GetCodeInfo2` with a zero-length `codeInfos` buffer to obtain the correct buffer size. You can then set the `codeInfos` buffer size to the value returned in `pcCodeInfos`, multiplied by the size of a `COR_PRF_CODE_INFO` structure, and call `GetCodeInfo2` again. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [GetCodeInfo3 Method](icorprofilerinfo4-getcodeinfo3-method.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo3-requestprofilerdetach-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo3-requestprofilerdetach-method.md index cde690c397717..41072ad82c28b 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo3-requestprofilerdetach-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo3-requestprofilerdetach-method.md @@ -2,68 +2,68 @@ description: "Learn more about: ICorProfilerInfo3::RequestProfilerDetach Method" title: "ICorProfilerInfo3::RequestProfilerDetach Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo3.RequestProfilerDetach Method" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo3::RequestProfilerDetach" -helpviewer_keywords: +helpviewer_keywords: - "RequestProfilerDetach method [.NET Framework profiling]" - "ICorProfilerInfo3::RequestProfilerDetach method [.NET Framework profiling]" ms.assetid: ea102e62-0454-4477-bcf3-126773acd184 -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo3::RequestProfilerDetach Method -Instructs the runtime to detach the profiler. - -## Syntax - -```cpp -HRESULT RequestProfilerDetach( - [in] DWORD dwExpectedCompletionMilliseconds); -``` - -## Parameters - - `dwExpectedCompletionMilliseconds` - [in] The length of time, in milliseconds, the common language runtime (CLR) should wait before checking to see whether it is safe to unload the profiler. - -## Return Value - - This method returns the following specific HRESULTs as well as HRESULT errors that indicate method failure. - -|HRESULT|Description| -|-------------|-----------------| -|S_OK|The detach request is valid, and the detach procedure is now continuing on another thread. When the detach is fully complete, a `ProfilerDetachSucceeded` event is issued.| -|E_CORPROF_E_CALLBACK3_REQUIRED|The profiler failed an [IUnknown::QueryInterface](/windows/win32/api/unknwn/nf-unknwn-iunknown-queryinterface(q)) attempt for the [ICorProfilerCallback3](icorprofilercallback3-interface.md) interface, which it must implement to support the detach operation. Detach was not attempted.| -|CORPROF_E_IMMUTABLE_FLAGS_SET|Detachment is impossible because the profiler set immutable flags at startup. Detachment was not attempted; the profiler is still fully attached.| -|CORPROF_E_IRREVERSIBLE_INSTRUMENTATION_PRESENT|Detachment is impossible because the profiler used instrumented Microsoft intermediate language (MSIL) code, or inserted `enter`/`leave` hooks. Detachment was not attempted; the profiler is still fully attached.

**Note** Instrumented MSIL is code is code that is provided by the profiler using the [SetILFunctionBody](icorprofilerinfo-setilfunctionbody-method.md) method.| -|CORPROF_E_RUNTIME_UNINITIALIZED|The runtime has not been initialized yet in the managed application. (That is, the runtime has not been fully loaded.) This error code may be returned when detachment is requested inside the profiler callback's [ICorProfilerCallback::Initialize](icorprofilercallback-initialize-method.md) method.| -|CORPROF_E_UNSUPPORTED_CALL_SEQUENCE|`RequestProfilerDetach` was called at an unsupported time. This occurs if the method is called on a managed thread but not from within an [ICorProfilerCallback](icorprofilercallback-interface.md) method or from within an [ICorProfilerCallback](icorprofilercallback-interface.md) method that cannot tolerate a garbage collection. For more information, see [CORPROF_E_UNSUPPORTED_CALL_SEQUENCE HRESULT](corprof-e-unsupported-call-sequence-hresult.md).| - -## Remarks - - During the detach procedure, the detach thread (the thread created specifically for detaching the profiler) occasionally checks whether all threads have exited the profiler’s code. The profiler should provide an estimate of how long this should take through the `dwExpectedCompletionMilliseconds` parameter. A good value to use is the typical amount of time the profiler spends inside any given `ICorProfilerCallback*` method; this value should not be less than half of the maximum amount of time the profiler expects to spend. - - The detach thread uses `dwExpectedCompletionMilliseconds` to decide how long to sleep before checking whether profiler callback code has been popped off all stacks. Although the details of the following algorithm may change in future releases of the CLR, it illustrates one way `dwExpectedCompletionMilliseconds` can be used when determining when it is safe to unload the profiler. The detach thread first sleeps for `dwExpectedCompletionMilliseconds` milliseconds. If, after awakening from the sleep, the CLR finds that profiler callback code is still present, the detach thread sleeps again, this time for two times `dwExpectedCompletionMilliseconds` milliseconds. If, after awakening from this second sleep, the detach thread finds that profiler callback code is still present, it sleeps for 10 minutes before checking again. The detach thread continues to recheck every 10 minutes. - - If the profiler specifies `dwExpectedCompletionMilliseconds` as 0 (zero), the CLR uses a default value of 5000, which means that it will perform a check after 5 seconds, again after 10 seconds, and then every 10 minutes thereafter. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v40plus](../../../../includes/net-current-v40plus-md.md)] - +Instructs the runtime to detach the profiler. + +## Syntax + +```cpp +HRESULT RequestProfilerDetach( + [in] DWORD dwExpectedCompletionMilliseconds); +``` + +## Parameters + + `dwExpectedCompletionMilliseconds` + [in] The length of time, in milliseconds, the common language runtime (CLR) should wait before checking to see whether it is safe to unload the profiler. + +## Return Value + + This method returns the following specific HRESULTs as well as HRESULT errors that indicate method failure. + +|HRESULT|Description| +|-------------|-----------------| +|S_OK|The detach request is valid, and the detach procedure is now continuing on another thread. When the detach is fully complete, a `ProfilerDetachSucceeded` event is issued.| +|E_CORPROF_E_CALLBACK3_REQUIRED|The profiler failed an [IUnknown::QueryInterface](/windows/win32/api/unknwn/nf-unknwn-iunknown-queryinterface(q)) attempt for the [ICorProfilerCallback3](icorprofilercallback3-interface.md) interface, which it must implement to support the detach operation. Detach was not attempted.| +|CORPROF_E_IMMUTABLE_FLAGS_SET|Detachment is impossible because the profiler set immutable flags at startup. Detachment was not attempted; the profiler is still fully attached.| +|CORPROF_E_IRREVERSIBLE_INSTRUMENTATION_PRESENT|Detachment is impossible because the profiler used instrumented common intermediate language (CIL) code, or inserted `enter`/`leave` hooks. Detachment was not attempted; the profiler is still fully attached.

**Note** Instrumented CIL is code is code that is provided by the profiler using the [SetILFunctionBody](icorprofilerinfo-setilfunctionbody-method.md) method.| +|CORPROF_E_RUNTIME_UNINITIALIZED|The runtime has not been initialized yet in the managed application. (That is, the runtime has not been fully loaded.) This error code may be returned when detachment is requested inside the profiler callback's [ICorProfilerCallback::Initialize](icorprofilercallback-initialize-method.md) method.| +|CORPROF_E_UNSUPPORTED_CALL_SEQUENCE|`RequestProfilerDetach` was called at an unsupported time. This occurs if the method is called on a managed thread but not from within an [ICorProfilerCallback](icorprofilercallback-interface.md) method or from within an [ICorProfilerCallback](icorprofilercallback-interface.md) method that cannot tolerate a garbage collection. For more information, see [CORPROF_E_UNSUPPORTED_CALL_SEQUENCE HRESULT](corprof-e-unsupported-call-sequence-hresult.md).| + +## Remarks + + During the detach procedure, the detach thread (the thread created specifically for detaching the profiler) occasionally checks whether all threads have exited the profiler’s code. The profiler should provide an estimate of how long this should take through the `dwExpectedCompletionMilliseconds` parameter. A good value to use is the typical amount of time the profiler spends inside any given `ICorProfilerCallback*` method; this value should not be less than half of the maximum amount of time the profiler expects to spend. + + The detach thread uses `dwExpectedCompletionMilliseconds` to decide how long to sleep before checking whether profiler callback code has been popped off all stacks. Although the details of the following algorithm may change in future releases of the CLR, it illustrates one way `dwExpectedCompletionMilliseconds` can be used when determining when it is safe to unload the profiler. The detach thread first sleeps for `dwExpectedCompletionMilliseconds` milliseconds. If, after awakening from the sleep, the CLR finds that profiler callback code is still present, the detach thread sleeps again, this time for two times `dwExpectedCompletionMilliseconds` milliseconds. If, after awakening from this second sleep, the detach thread finds that profiler callback code is still present, it sleeps for 10 minutes before checking again. The detach thread continues to recheck every 10 minutes. + + If the profiler specifies `dwExpectedCompletionMilliseconds` as 0 (zero), the CLR uses a default value of 5000, which means that it will perform a check after 5 seconds, again after 10 seconds, and then every 10 minutes thereafter. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v40plus](../../../../includes/net-current-v40plus-md.md)] + ## See also - [ICorProfilerInfo3 Interface](icorprofilerinfo3-interface.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-getiltonativemapping2-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-getiltonativemapping2-method.md index df9595c3e32e9..5767b4f408b3c 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-getiltonativemapping2-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-getiltonativemapping2-method.md @@ -2,77 +2,77 @@ description: "Learn more about: ICorProfilerInfo4::GetILToNativeMapping2 Method" title: "ICorProfilerInfo4::GetILToNativeMapping2 Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo4.GetILToNativeMapping2" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo4::GetILToNativeMapping2" -helpviewer_keywords: +helpviewer_keywords: - "ICorProfilerInfo4::GetILToNativeMapping2 method [.NET Framework profiling]" - "GetILToNativeMapping2 method, ICorProfilerInfo4 interface [.NET Framework profiling]" ms.assetid: 756c1c25-08a7-4060-9798-dbeaa2f3bee5 -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo4::GetILToNativeMapping2 Method -Gets a map from Microsoft intermediate language (MSIL) offsets to native offsets for the code contained in the JIT-recompiled version of the specified function. - -## Syntax - -```cpp -HRESULT GetILToNativeMapping2( - [in] FunctionID functionId, - [in] ReJITID reJitId, - [in] ULONG32 cMap, - [out] ULONG32 *pcMap, - [out, size_is(cMap), length_is(*pcMap)] - COR_DEBUG_IL_TO_NATIVE_MAP map[]); -``` - -## Parameters - - `functionId` - [in] The ID of the function that contains the code. - - `pReJitId` - [in] The identity of the JIT-recompiled function. The identity must be zero in .NET Framework 4.5. - - `cMap` - [in] The maximum size of the `map` array. - - `pcMap` - [out] The total number of available COR_DEBUG_IL_TO_NATIVE_MAP structures. - - `map` - [out] An array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures, each of which specifies the offsets. After the `GetILToNativeMapping2` method returns, `map` will contain some or all of the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. - -## Remarks - - `GetILToNativeMapping2` is similar to the [ICorProfilerInfo::GetILToNativeMapping](icorprofilerinfo-getiltonativemapping-method.md) method, except that it will allow the profiler to specify the ID of the recompiled function in future releases. - +Gets a map from common intermediate language (CIL) offsets to native offsets for the code contained in the JIT-recompiled version of the specified function. + +## Syntax + +```cpp +HRESULT GetILToNativeMapping2( + [in] FunctionID functionId, + [in] ReJITID reJitId, + [in] ULONG32 cMap, + [out] ULONG32 *pcMap, + [out, size_is(cMap), length_is(*pcMap)] + COR_DEBUG_IL_TO_NATIVE_MAP map[]); +``` + +## Parameters + + `functionId` + [in] The ID of the function that contains the code. + + `pReJitId` + [in] The identity of the JIT-recompiled function. The identity must be zero in .NET Framework 4.5. + + `cMap` + [in] The maximum size of the `map` array. + + `pcMap` + [out] The total number of available COR_DEBUG_IL_TO_NATIVE_MAP structures. + + `map` + [out] An array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures, each of which specifies the offsets. After the `GetILToNativeMapping2` method returns, `map` will contain some or all of the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. + +## Remarks + + `GetILToNativeMapping2` is similar to the [ICorProfilerInfo::GetILToNativeMapping](icorprofilerinfo-getiltonativemapping-method.md) method, except that it will allow the profiler to specify the ID of the recompiled function in future releases. + > [!NOTE] -> The [ICorProfilerFunctionControl::SetILInstrumentedCodeMap](icorprofilerfunctioncontrol-setilinstrumentedcodemap-method.md) method is not implemented in .NET Framework 4.5, so functions that have been JIT-recompiled cannot have an IL-to-native mapping that differs from the originally compiled function. As such, `GetILToNativeMapping2` cannot be called with a nonzero JIT-recompiled ID in .NET Framework 4.5. - - The `GetILToNativeMapping2` method returns an array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To convey that certain ranges of native instructions correspond to special regions of code (for example, the prolog), an entry in the array can have its `ilOffset` field set to a value of the [CorDebugIlToNativeMappingTypes](../debugging/cordebugiltonativemappingtypes-enumeration.md) enumeration. - - After `GetILToNativeMapping2` returns, you must verify that the `map` buffer was large enough to contain all the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To do this, compare the value of `cMap` with the value of the `pcMap` parameter. If the `pcMap` value, when it is multiplied by the size of a `COR_DEBUG_IL_TO_NATIVE_MAP` structure, is larger than `cMap`, allocate a larger `map` buffer, update `cMap` with the new, larger size, and call `GetILToNativeMapping2` again. - - Alternatively, you can first call `GetILToNativeMapping2` with a zero-length `map` buffer to obtain the correct buffer size. You can then set the buffer size to the value returned in `pcMap` and call `GetILToNativeMapping2` again. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v45plus](../../../../includes/net-current-v45plus-md.md)] - +> The [ICorProfilerFunctionControl::SetILInstrumentedCodeMap](icorprofilerfunctioncontrol-setilinstrumentedcodemap-method.md) method is not implemented in .NET Framework 4.5, so functions that have been JIT-recompiled cannot have an IL-to-native mapping that differs from the originally compiled function. As such, `GetILToNativeMapping2` cannot be called with a nonzero JIT-recompiled ID in .NET Framework 4.5. + + The `GetILToNativeMapping2` method returns an array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To convey that certain ranges of native instructions correspond to special regions of code (for example, the prolog), an entry in the array can have its `ilOffset` field set to a value of the [CorDebugIlToNativeMappingTypes](../debugging/cordebugiltonativemappingtypes-enumeration.md) enumeration. + + After `GetILToNativeMapping2` returns, you must verify that the `map` buffer was large enough to contain all the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To do this, compare the value of `cMap` with the value of the `pcMap` parameter. If the `pcMap` value, when it is multiplied by the size of a `COR_DEBUG_IL_TO_NATIVE_MAP` structure, is larger than `cMap`, allocate a larger `map` buffer, update `cMap` with the new, larger size, and call `GetILToNativeMapping2` again. + + Alternatively, you can first call `GetILToNativeMapping2` with a zero-length `map` buffer to obtain the correct buffer size. You can then set the buffer size to the value returned in `pcMap` and call `GetILToNativeMapping2` again. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v45plus](../../../../includes/net-current-v45plus-md.md)] + ## See also - [GetILToNativeMapping Method](icorprofilerinfo-getiltonativemapping-method.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-interface.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-interface.md index b68c3935504bf..72cdbcf28e66e 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-interface.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-interface.md @@ -2,53 +2,53 @@ description: "Learn more about: ICorProfilerInfo4 Interface" title: "ICorProfilerInfo4 Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo4" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo4" -helpviewer_keywords: +helpviewer_keywords: - "ICorProfilerInfo4 interface [.NET Framework profiling]" ms.assetid: 80a5308e-c22f-4201-ba89-31cc8562515b -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo4 Interface -Provides methods that code profilers use to communicate with the common language runtime (CLR) to control event monitoring and request information. . The `ICorProfilerInfo4` interface is an extension of the other `ICorProfilerInfo` interfaces. It provides new methods to support just-in-time (JIT) recompilation, added in .NET Framework 4.5. - -## Methods - -|Method|Description| -|------------|-----------------| -|[EnumJITedFunctions2 Method](icorprofilerinfo4-enumjitedfunctions2-method.md)|Returns an enumerator for all functions that were previously JIT-compiled and JIT-recompiled.| -|[EnumThreads Method](icorprofilerinfo4-enumthreads-method.md)|Gets an enumerator that provides methods to sequentially iterate through the collection of all managed threads in the profiled process.| -|[GetCodeInfo3 Method](icorprofilerinfo4-getcodeinfo3-method.md)|Gets the extents of native code associated with the JIT-recompiled version of the specified function.| -|[GetFunctionFromIP2 Method](icorprofilerinfo4-getfunctionfromip2-method.md)|Maps a managed code instruction pointer to the JIT-recompiled version of a specified function.| -|[GetILToNativeMapping2 Method](icorprofilerinfo4-getiltonativemapping2-method.md)|Gets a map from Microsoft intermediate language (MSIL) offsets to native offsets for the code contained in the JIT-recompiled version of the specified function .| -|[GetObjectSize2 Method](icorprofilerinfo4-getobjectsize2-method.md)|Returns the size of a specified object.| -|[GetReJITIDs Method](icorprofilerinfo4-getrejitids-method.md)|Returns an array of IDs that identify all JIT-recompiled versions of the specified function that are still allocated.| -|[InitializeCurrentThread Method](icorprofilerinfo4-initializecurrentthread-method.md)|Initializes the current thread in advance of subsequent profiler API calls on the same thread, so that deadlock can be avoided.| -|[RequestReJIT Method](icorprofilerinfo4-requestrejit-method.md)|Requests a JIT recompilation of all instances of the specified functions.| -|[RequestRevert Method](icorprofilerinfo4-requestrevert-method.md)|Reverts all instances of the specified functions to their original versions.| - -## Remarks - - The CLR implements the methods of the `ICorProfilerInfo4` interface by using the free-threaded model. Each method returns an HRESULT to indicate success or failure. For a list of possible return codes, see the CorError.h file. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v45plus](../../../../includes/net-current-v45plus-md.md)] - +Provides methods that code profilers use to communicate with the common language runtime (CLR) to control event monitoring and request information. . The `ICorProfilerInfo4` interface is an extension of the other `ICorProfilerInfo` interfaces. It provides new methods to support just-in-time (JIT) recompilation, added in .NET Framework 4.5. + +## Methods + +|Method|Description| +|------------|-----------------| +|[EnumJITedFunctions2 Method](icorprofilerinfo4-enumjitedfunctions2-method.md)|Returns an enumerator for all functions that were previously JIT-compiled and JIT-recompiled.| +|[EnumThreads Method](icorprofilerinfo4-enumthreads-method.md)|Gets an enumerator that provides methods to sequentially iterate through the collection of all managed threads in the profiled process.| +|[GetCodeInfo3 Method](icorprofilerinfo4-getcodeinfo3-method.md)|Gets the extents of native code associated with the JIT-recompiled version of the specified function.| +|[GetFunctionFromIP2 Method](icorprofilerinfo4-getfunctionfromip2-method.md)|Maps a managed code instruction pointer to the JIT-recompiled version of a specified function.| +|[GetILToNativeMapping2 Method](icorprofilerinfo4-getiltonativemapping2-method.md)|Gets a map from common intermediate language (CIL) offsets to native offsets for the code contained in the JIT-recompiled version of the specified function .| +|[GetObjectSize2 Method](icorprofilerinfo4-getobjectsize2-method.md)|Returns the size of a specified object.| +|[GetReJITIDs Method](icorprofilerinfo4-getrejitids-method.md)|Returns an array of IDs that identify all JIT-recompiled versions of the specified function that are still allocated.| +|[InitializeCurrentThread Method](icorprofilerinfo4-initializecurrentthread-method.md)|Initializes the current thread in advance of subsequent profiler API calls on the same thread, so that deadlock can be avoided.| +|[RequestReJIT Method](icorprofilerinfo4-requestrejit-method.md)|Requests a JIT recompilation of all instances of the specified functions.| +|[RequestRevert Method](icorprofilerinfo4-requestrevert-method.md)|Reverts all instances of the specified functions to their original versions.| + +## Remarks + + The CLR implements the methods of the `ICorProfilerInfo4` interface by using the free-threaded model. Each method returns an HRESULT to indicate success or failure. For a list of possible return codes, see the CorError.h file. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v45plus](../../../../includes/net-current-v45plus-md.md)] + ## See also - [Profiling Interfaces](profiling-interfaces.md) diff --git a/docs/framework/unmanaged-api/profiling/imethodmalloc-alloc-method.md b/docs/framework/unmanaged-api/profiling/imethodmalloc-alloc-method.md index e1c9ac27cb39b..3242f2359b9af 100644 --- a/docs/framework/unmanaged-api/profiling/imethodmalloc-alloc-method.md +++ b/docs/framework/unmanaged-api/profiling/imethodmalloc-alloc-method.md @@ -20,7 +20,7 @@ topic_type: # IMethodMalloc::Alloc Method -Attempts to allocate a specified amount of memory for a new Microsoft intermediate language (MSIL) function body. +Attempts to allocate a specified amount of memory for a new common intermediate language (CIL) function body. ## Syntax diff --git a/docs/framework/unmanaged-api/profiling/imethodmalloc-interface.md b/docs/framework/unmanaged-api/profiling/imethodmalloc-interface.md index 661b6c3ac8932..e5ed65cdf302d 100644 --- a/docs/framework/unmanaged-api/profiling/imethodmalloc-interface.md +++ b/docs/framework/unmanaged-api/profiling/imethodmalloc-interface.md @@ -2,47 +2,47 @@ description: "Learn more about: IMethodMalloc Interface" title: "IMethodMalloc Interface" ms.date: "03/30/2017" -api_name: +api_name: - "IMethodMalloc" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "IMethodMalloc" -helpviewer_keywords: +helpviewer_keywords: - "IMethodMalloc interface [.NET Framework profiling]" ms.assetid: 8c8ab5dc-557c-473a-82f2-6e403eca7dac -topic_type: +topic_type: - "apiref" --- # IMethodMalloc Interface -Provides a method to allocate memory for a new Microsoft intermediate language (MSIL) function body. - +Provides a method to allocate memory for a new common intermediate language (CIL) function body. + > [!NOTE] -> The `IMethodMalloc` interface is a simple memory allocator. It allows you to allocate memory, but not to free it. - -## Methods - -|Method|Description| -|------------|-----------------| -|[Alloc Method](imethodmalloc-alloc-method.md)|Attempts to allocate a specified amount of memory for a new MSIL function body.| - -## Remarks - - Each allocator is module-specific and ensures that the function body will be at a positive offset from the base of the module. Memory above the base of a module can be precious, so the allocator should be used to allocate memory only for a function body. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +> The `IMethodMalloc` interface is a simple memory allocator. It allows you to allocate memory, but not to free it. + +## Methods + +|Method|Description| +|------------|-----------------| +|[Alloc Method](imethodmalloc-alloc-method.md)|Attempts to allocate a specified amount of memory for a new CIL function body.| + +## Remarks + + Each allocator is module-specific and ensures that the function body will be at a positive offset from the base of the module. Memory above the base of a module can be precious, so the allocator should be used to allocate memory only for a function body. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [Profiling Interfaces](profiling-interfaces.md) diff --git a/docs/framework/unmanaged-api/profiling/profiling-interfaces.md b/docs/framework/unmanaged-api/profiling/profiling-interfaces.md index 66fa3f2db12bd..4a8a0a92a71bd 100644 --- a/docs/framework/unmanaged-api/profiling/profiling-interfaces.md +++ b/docs/framework/unmanaged-api/profiling/profiling-interfaces.md @@ -105,7 +105,7 @@ Provides methods to sequentially iterate through a collection of frozen objects Provides methods to sequentially iterate through a collection of threads in the CLR. [IMethodMalloc Interface](imethodmalloc-interface.md)\ -Provides the [Alloc](imethodmalloc-alloc-method.md) method to allocate memory for a new Microsoft intermediate language (MSIL) function body. +Provides the [Alloc](imethodmalloc-alloc-method.md) method to allocate memory for a new common intermediate language (CIL) function body. ## Related Sections diff --git a/docs/framework/unmanaged-api/profiling/profiling-overview.md b/docs/framework/unmanaged-api/profiling/profiling-overview.md index c70c1aaaaca96..38f91aa7b0e24 100644 --- a/docs/framework/unmanaged-api/profiling/profiling-overview.md +++ b/docs/framework/unmanaged-api/profiling/profiling-overview.md @@ -35,9 +35,9 @@ A profiler is a tool that monitors the execution of another application. A commo Traditional profiling tools focus on measuring the execution of the application. That is, they measure the time that is spent in each function or the memory usage of the application over time. The profiling API targets a broader class of diagnostic tools such as code-coverage utilities and even advanced debugging aids. These uses are all diagnostic in nature. The profiling API not only measures but also monitors the execution of an application. For this reason, the profiling API should never be used by the application itself, and the application’s execution should not depend on (or be affected by) the profiler. -Profiling a CLR application requires more support than profiling conventionally compiled machine code. This is because the CLR introduces concepts such as application domains, garbage collection, managed exception handling, just-in-time (JIT) compilation of code (converting Microsoft intermediate language, or MSIL, code into native machine code), and similar features. Conventional profiling mechanisms cannot identify or provide useful information about these features. The profiling API provides this missing information efficiently, with minimal effect on the performance of the CLR and the profiled application. +Profiling a CLR application requires more support than profiling conventionally compiled machine code. This is because the CLR introduces concepts such as application domains, garbage collection, managed exception handling, just-in-time (JIT) compilation of code (converting common intermediate language, or CIL, code into native machine code), and similar features. Conventional profiling mechanisms cannot identify or provide useful information about these features. The profiling API provides this missing information efficiently, with minimal effect on the performance of the CLR and the profiled application. -JIT compilation at run time provides good opportunities for profiling. The profiling API enables a profiler to change the in-memory MSIL code stream for a routine before it is JIT-compiled. In this manner, the profiler can dynamically add instrumentation code to particular routines that need deeper investigation. Although this approach is possible in conventional scenarios, it is much easier to implement for the CLR by using the profiling API. +JIT compilation at run time provides good opportunities for profiling. The profiling API enables a profiler to change the in-memory CIL code stream for a routine before it is JIT-compiled. In this manner, the profiler can dynamically add instrumentation code to particular routines that need deeper investigation. Although this approach is possible in conventional scenarios, it is much easier to implement for the CLR by using the profiling API. ## The Profiling API @@ -138,11 +138,11 @@ A review of the CLR profiling API may create the impression that you can write a Although this is possible from a design perspective, the profiling API does not support managed components. A CLR profiler must be completely unmanaged. Attempts to combine managed and unmanaged code in a CLR profiler may cause access violations, program failure, or deadlocks. The managed components of the profiler will fire events back to their unmanaged components, which would subsequently call the managed components again, resulting in circular references. -The only location where a CLR profiler can call managed code safely is in the Microsoft intermediate language (MSIL) body of a method. The recommended practice for modifying the MSIL body is to use the JIT recompilation methods in the [ICorProfilerCallback4](icorprofilercallback4-interface.md) interface. +The only location where a CLR profiler can call managed code safely is in the common intermediate language (CIL) body of a method. The recommended practice for modifying the CIL body is to use the JIT recompilation methods in the [ICorProfilerCallback4](icorprofilercallback4-interface.md) interface. -It is also possible to use the older instrumentation methods to modify MSIL. Before the just-in-time (JIT) compilation of a function is completed, the profiler can insert managed calls in the MSIL body of a method and then JIT-compile it (see the [ICorProfilerInfo::GetILFunctionBody](icorprofilerinfo-getilfunctionbody-method.md) method). This technique can successfully be used for selective instrumentation of managed code, or to gather statistics and performance data about the JIT. +It is also possible to use the older instrumentation methods to modify CIL. Before the just-in-time (JIT) compilation of a function is completed, the profiler can insert managed calls in the CIL body of a method and then JIT-compile it (see the [ICorProfilerInfo::GetILFunctionBody](icorprofilerinfo-getilfunctionbody-method.md) method). This technique can successfully be used for selective instrumentation of managed code, or to gather statistics and performance data about the JIT. -Alternatively, a code profiler can insert native hooks in the MSIL body of every managed function that calls into unmanaged code. This technique can be used for instrumentation and coverage. For example, a code profiler could insert instrumentation hooks after every MSIL block to ensure that the block has been executed. The modification of the MSIL body of a method is a very delicate operation, and there are many factors that should be taken into consideration. +Alternatively, a code profiler can insert native hooks in the CIL body of every managed function that calls into unmanaged code. This technique can be used for instrumentation and coverage. For example, a code profiler could insert instrumentation hooks after every CIL block to ensure that the block has been executed. The modification of the CIL body of a method is a very delicate operation, and there are many factors that should be taken into consideration. ## Profiling Unmanaged Code diff --git a/docs/fsharp/language-reference/operator-overloading.md b/docs/fsharp/language-reference/operator-overloading.md index 1c4521b831f49..4efd8dae1dbd8 100644 --- a/docs/fsharp/language-reference/operator-overloading.md +++ b/docs/fsharp/language-reference/operator-overloading.md @@ -45,7 +45,7 @@ A table that shows the precedence of all operators in F# can be found in [Symbol ## Overloaded Operator Names -When the F# compiler compiles an operator expression, it generates a method that has a compiler-generated name for that operator. This is the name that appears in the Microsoft intermediate language (MSIL) for the method, and also in reflection and IntelliSense. You do not normally need to use these names in F# code. +When the F# compiler compiles an operator expression, it generates a method that has a compiler-generated name for that operator. This is the name that appears in the common intermediate language (CIL) for the method, and also in reflection and IntelliSense. You do not normally need to use these names in F# code. The following table shows the standard operators and their corresponding generated names. diff --git a/docs/fsharp/language-reference/type-abbreviations.md b/docs/fsharp/language-reference/type-abbreviations.md index 58d4e021ae726..1d0df25d72af5 100644 --- a/docs/fsharp/language-reference/type-abbreviations.md +++ b/docs/fsharp/language-reference/type-abbreviations.md @@ -3,7 +3,7 @@ title: Type Abbreviations description: Learn about F# type abbreviations to give a type a more meaningful name in order to make code easier to read. ms.date: 05/16/2016 --- -# Type Abbreviations +# Type abbreviations A *type abbreviation* is an alias or alternate name for a type. @@ -27,7 +27,7 @@ Type abbreviations can include generic parameters, as in the following code. In the previous code, `Transform` is a type abbreviation that represents a function that takes a single argument of any type and that returns a single value of that same type. -Type abbreviations are not preserved in the .NET Framework MSIL code. Therefore, when you use an F# assembly from another .NET Framework language, you must use the underlying type name for a type abbreviation. +Type abbreviations are not preserved in common intermediate language (CIL) code. Therefore, when you use an F# assembly from another .NET language, you must use the underlying type name for a type abbreviation. Type abbreviations can also be used on units of measure. For more information, see [Units of Measure](units-of-measure.md). diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1810.md b/docs/fundamentals/code-analysis/quality-rules/ca1810.md index be4fe44080d63..ed296fcf359d7 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1810.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1810.md @@ -32,7 +32,7 @@ A reference type declares an explicit static constructor. When a type declares an explicit static constructor, the just-in-time (JIT) compiler adds a check to each static method and instance constructor of the type to make sure that the static constructor was previously called. Static initialization is triggered when any static member is accessed or when an instance of the type is created. However, static initialization is not triggered if you declare a variable of the type but do not use it, which can be important if the initialization changes global state. -When all static data is initialized inline and an explicit static constructor is not declared, Microsoft intermediate language (MSIL) compilers add the `beforefieldinit` flag and an implicit static constructor, which initializes the static data, to the MSIL type definition. When the JIT compiler encounters the `beforefieldinit` flag, most of the time the static constructor checks are not added. Static initialization is guaranteed to occur at some time before any static fields are accessed but not before a static method or instance constructor is invoked. Note that static initialization can occur at any time after a variable of the type is declared. +When all static data is initialized inline and an explicit static constructor is not declared, common intermediate language (CIL) compilers add the `beforefieldinit` flag and an implicit static constructor, which initializes the static data, to the CIL type definition. When the JIT compiler encounters the `beforefieldinit` flag, most of the time the static constructor checks are not added. Static initialization is guaranteed to occur at some time before any static fields are accessed but not before a static method or instance constructor is invoked. Note that static initialization can occur at any time after a variable of the type is declared. Static constructor checks can decrease performance. Often a static constructor is used only to initialize static fields, in which case you must only make sure that static initialization occurs before the first access of a static field. The `beforefieldinit` behavior is appropriate for these and most other types. It is only inappropriate when static initialization affects global state and one of the following is true: @@ -78,7 +78,7 @@ The following example shows a type, `StaticConstructor`, that violates the rule :::code language="vb" source="snippets/vb/all-rules/ca1810-initialize-reference-type-static-fields-inline_1.vb"::: -Note the addition of the `beforefieldinit` flag on the MSIL definition for the `NoStaticConstructor` class. +Note the addition of the `beforefieldinit` flag on the CIL definition for the `NoStaticConstructor` class. ```il .class public auto ansi StaticConstructor diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1820.md b/docs/fundamentals/code-analysis/quality-rules/ca1820.md index 8f96e179f5fd5..cc581da0d0515 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1820.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1820.md @@ -27,7 +27,7 @@ A string is compared to the empty string by using property or the method is faster than using . This is because executes significantly more MSIL instructions than either or the number of instructions executed to retrieve the property value and compare it to zero. +Comparing strings using the property or the method is faster than using . This is because executes significantly more CIL instructions than either or the number of instructions executed to retrieve the property value and compare it to zero. For null strings, and `.Length == 0` behave differently. If you try to get the value of the property on a null string, the common language runtime throws a . If you perform a comparison between a null string and the empty string, the common language runtime does not throw an exception and returns `false`. Testing for null does not significantly affect the relative performance of these two approaches. When targeting .NET Framework 2.0 or later, use the method. Otherwise, use the == 0 comparison whenever possible. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2207.md b/docs/fundamentals/code-analysis/quality-rules/ca2207.md index 584eaebe98c57..b97b850371006 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2207.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2207.md @@ -29,7 +29,7 @@ A value-type declares an explicit static constructor. When a value-type is declared, it undergoes a default initialization where all value-type fields are set to zero and all reference-type fields are set to `null` (`Nothing` in Visual Basic). An explicit static constructor is only guaranteed to run before an instance constructor or static member of the type is called. Therefore, if the type is created without calling an instance constructor, the static constructor is not guaranteed to run. -If all static data is initialized inline and no explicit static constructor is declared, the C# and Visual Basic compilers add the `beforefieldinit` flag to the MSIL class definition. The compilers also add a private static constructor that contains the static initialization code. This private static constructor is guaranteed to run before any static fields of the type are accessed. +If all static data is initialized inline and no explicit static constructor is declared, the C# and Visual Basic compilers add the `beforefieldinit` flag to the CIL class definition. The compilers also add a private static constructor that contains the static initialization code. This private static constructor is guaranteed to run before any static fields of the type are accessed. ## How to fix violations diff --git a/docs/fundamentals/runtime-libraries/system-collections-generic-list{t}.md b/docs/fundamentals/runtime-libraries/system-collections-generic-list{t}.md index 1157bcdb49e6f..78d7bd44ce29c 100644 --- a/docs/fundamentals/runtime-libraries/system-collections-generic-list{t}.md +++ b/docs/fundamentals/runtime-libraries/system-collections-generic-list{t}.md @@ -39,7 +39,7 @@ If a value type is used for type `T`, the compiler generates an implementation o Make certain the value type used for type `T` implements the generic interface. If not, methods such as must call the method, which boxes the affected list element. If the value type implements the interface and you own the source code, also implement the generic interface to prevent the and methods from boxing list elements. If you do not own the source code, pass an object to the and methods. -It's to your advantage to use the type-specific implementation of the class instead of using the class or writing a strongly typed wrapper collection yourself. That's because your implementation must do what .NET does for you already, and the .NET runtime can share Microsoft intermediate language code and metadata, which your implementation cannot. +It's to your advantage to use the type-specific implementation of the class instead of using the class or writing a strongly typed wrapper collection yourself. That's because your implementation must do what .NET does for you already, and the .NET runtime can share common intermediate language code and metadata, which your implementation cannot. ## F# considerations diff --git a/docs/fundamentals/runtime-libraries/system-invalidoperationexception.md b/docs/fundamentals/runtime-libraries/system-invalidoperationexception.md index 0d08dc01dd94e..b83d1d4072e7c 100644 --- a/docs/fundamentals/runtime-libraries/system-invalidoperationexception.md +++ b/docs/fundamentals/runtime-libraries/system-invalidoperationexception.md @@ -247,7 +247,7 @@ Calling the ### Dynamic cross-application domain field access -The Microsoft intermediate language (MSIL) instruction throws an exception if the object containing the field whose address you are trying to retrieve is not within the application domain in which your code is executing. The address of a field can only be accessed from the application domain in which it resides. +The common intermediate language (CIL) instruction throws an exception if the object containing the field whose address you are trying to retrieve is not within the application domain in which your code is executing. The address of a field can only be accessed from the application domain in which it resides. ## Throw an InvalidOperationException exception diff --git a/docs/fundamentals/runtime-libraries/system-reflection-emit-methodbuilder.md b/docs/fundamentals/runtime-libraries/system-reflection-emit-methodbuilder.md index dc22f9c61270f..4d1dffa1f5a7a 100644 --- a/docs/fundamentals/runtime-libraries/system-reflection-emit-methodbuilder.md +++ b/docs/fundamentals/runtime-libraries/system-reflection-emit-methodbuilder.md @@ -7,7 +7,7 @@ ms.date: 12/31/2023 [!INCLUDE [context](includes/context.md)] -The class is used to fully describe a method in Microsoft intermediate language (MSIL), including the name, attributes, signature, and method body. It is used in conjunction with the class to create classes at runtime. +The class is used to fully describe a method in common intermediate language (CIL), including the name, attributes, signature, and method body. It is used in conjunction with the class to create classes at runtime. You can use reflection emit to define global methods and to define methods as type members. The APIs that define methods return objects. diff --git a/docs/fundamentals/runtime-libraries/system-type-gettype.md b/docs/fundamentals/runtime-libraries/system-type-gettype.md index 29b2e5676e79c..7bb9efc978d09 100644 --- a/docs/fundamentals/runtime-libraries/system-type-gettype.md +++ b/docs/fundamentals/runtime-libraries/system-type-gettype.md @@ -106,7 +106,7 @@ Because this assembly is neither mscorlib.dll/System.Private.CoreLib.dll nor the Certain characters have special meanings in assembly-qualified names. If a simple type name contains these characters, the characters cause parsing errors when the simple name is part of an assembly-qualified name. To avoid the parsing errors, you must escape the special characters with a backslash before you can pass the assembly-qualified name to the method. For example, if a type is named `Strange]Type`, the escape character must be added ahead of the square bracket as follows: `Strange\]Type`. > [!NOTE] -> Names with such special characters cannot be created in Visual Basic or C#, but can be created by using Microsoft intermediate language (MSIL) or by emitting dynamic assemblies. +> Names with such special characters cannot be created in Visual Basic or C#, but can be created by using common intermediate language (CIL) or by emitting dynamic assemblies. The following table shows the special characters for type names. diff --git a/docs/fundamentals/runtime-libraries/system-type-makegenerictype.md b/docs/fundamentals/runtime-libraries/system-type-makegenerictype.md index ef077f587f84b..005e23cf3b7e1 100644 --- a/docs/fundamentals/runtime-libraries/system-type-makegenerictype.md +++ b/docs/fundamentals/runtime-libraries/system-type-makegenerictype.md @@ -44,7 +44,7 @@ If the parameter list of the enclosing type has more than one type parameter, al To construct a generic type from the generic type definition for a nested type, call the method with the array formed by concatenating the type argument arrays of all the enclosing types, beginning with the outermost generic type, and ending with the type argument array of the nested type itself, if it has type parameters of its own. To create an instance of `Innermost1`, call the method with an array containing three types, to be assigned to T, U, and V. To create an instance of `Innermost2`, call the method with an array containing two types, to be assigned to T and U. -The languages propagate the type parameters of enclosing types in this fashion so you can use the type parameters of an enclosing type to define fields of nested types. Otherwise, the type parameters would not be in scope within the bodies of the nested types. It is possible to define nested types without propagating the type parameters of enclosing types, by emitting code in dynamic assemblies or by using the [Ilasm.exe (IL Assembler)](../../framework/tools/ilasm-exe-il-assembler.md). Consider the following code for the MSIL assembler: +The languages propagate the type parameters of enclosing types in this fashion so you can use the type parameters of an enclosing type to define fields of nested types. Otherwise, the type parameters would not be in scope within the bodies of the nested types. It is possible to define nested types without propagating the type parameters of enclosing types, by emitting code in dynamic assemblies or by using the [Ilasm.exe (IL Assembler)](../../framework/tools/ilasm-exe-il-assembler.md). Consider the following code for the CIL assembler: ```msil .class public Outer { diff --git a/docs/standard/assembly/contents.md b/docs/standard/assembly/contents.md index a0e23288ac81a..4dfb83d1d09e4 100644 --- a/docs/standard/assembly/contents.md +++ b/docs/standard/assembly/contents.md @@ -1,8 +1,8 @@ --- title: Assembly contents -description: This article describes the contents of a .NET assembly, which can include assembly metadata, type metadata, MSIL code, and resources. +description: This article describes the contents of a .NET assembly, which can include assembly metadata, type metadata, CIL code, and resources. ms.date: "08/20/2019" -helpviewer_keywords: +helpviewer_keywords: - "assemblies [.NET Framework]" - "assemblies [.NET Core]" - "single-file assemblies" @@ -16,7 +16,7 @@ In general, a static assembly can consist of four elements: - Type metadata. -- Microsoft intermediate language (MSIL) code that implements the types. It is generated by the compiler from one or more source code files. +- Common intermediate language (CIL) code that implements the types. It is generated by the compiler from one or more source code files. - A set of [resources](../../core/extensions/resources.md). diff --git a/docs/standard/assembly/identify.md b/docs/standard/assembly/identify.md index ffb1cfa9bed46..4125f0ade5b27 100644 --- a/docs/standard/assembly/identify.md +++ b/docs/standard/assembly/identify.md @@ -3,37 +3,36 @@ title: "How to: Determine if a file is an assembly" description: This article shows you how determine whether a file is a .NET assembly, both manually and programmatically. ms.date: 07/24/2021 ms.topic: how-to -dev_langs: +dev_langs: - "csharp" - "vb" --- # How to: Determine if a file is an assembly -A file is an assembly if and only if it is managed, and contains an assembly entry in its metadata. For more information on assemblies and metadata, see [Assembly manifest](manifest.md). - -## How to manually determine if a file is an assembly - -1. Start the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md). - -2. Load the file you want to test. - -3. If **ILDASM** reports that the file is not a portable executable (PE) file, then it is not an assembly. For more information, see the topic [How to: View assembly contents](view-contents.md). - -## How to programmatically determine if a file is an assembly +A file is an assembly if and only if it is managed, and contains an assembly entry in its metadata. For more information on assemblies and metadata, see [Assembly manifest](manifest.md). + +## How to manually determine if a file is an assembly + +1. Start the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) tool. + +2. Load the file you want to test. + +3. If **ILDASM** reports that the file is not a portable executable (PE) file, then it is not an assembly. For more information, see the topic [How to: View assembly contents](view-contents.md). + +## How to programmatically determine if a file is an assembly ### Using the AssemblyName class -1. Call the method, passing the full file path and name of the file you are testing. - -2. If a exception is thrown, the file is not an assembly. +1. Call the method, passing the full file path and name of the file you are testing. -This example tests a DLL to see if it is an assembly. +2. If a exception is thrown, the file is not an assembly. -[!code-csharp[](snippets/identify/csharp/ExampleAssemblyName.cs#AssemblyName)] +This example tests a DLL to see if it is an assembly. +[!code-csharp[](snippets/identify/csharp/ExampleAssemblyName.cs#AssemblyName)] [!code-vb[](snippets/identify/visual-basic/ExampleAssemblyName.vb#AssemblyName)] -The method loads the test file, and then releases it once the information is read. +The method loads the test file, and then releases it once the information is read. ### Using the PEReader class @@ -54,7 +53,6 @@ Unlike the method, the This example shows how to determine if a file is an assembly using the class. [!code-csharp[](snippets/identify/csharp/ExamplePeReader.cs#PeReader)] - [!code-vb[](snippets/identify/visual-basic/ExamplePeReader.vb#PeReader)] ## See also diff --git a/docs/standard/assembly/index.md b/docs/standard/assembly/index.md index c2cfe1b6444a6..6a201aee40e4b 100644 --- a/docs/standard/assembly/index.md +++ b/docs/standard/assembly/index.md @@ -46,7 +46,7 @@ An assembly defines the following information: - The **type boundary**. Every type's identity includes the name of the assembly in which it resides. A type called `MyType` that's loaded in the scope of one assembly isn't the same as a type called `MyType` that's loaded in the scope of another assembly. -- The **reference-scope boundary**: The [assembly manifest](#assembly-manifest) has metadata that's used for resolving types and satisfying resource requests. The manifest specifies the types and resources to expose outside the assembly and enumerates other assemblies on which it depends. Microsoft intermediate language (MSIL) code in a portable executable (PE) file won't be executed unless it has an associated [assembly manifest](#assembly-manifest). +- The **reference-scope boundary**: The [assembly manifest](#assembly-manifest) has metadata that's used for resolving types and satisfying resource requests. The manifest specifies the types and resources to expose outside the assembly and enumerates other assemblies on which it depends. Common intermediate language (CIL) code in a portable executable (PE) file won't be executed unless it has an associated [assembly manifest](#assembly-manifest). - The **version boundary**. The assembly is the smallest versionable unit in the common language runtime. All types and resources in the same assembly are versioned as a unit. The [assembly manifest](#assembly-manifest) describes the version dependencies you specify for any dependent assemblies. For more information about versioning, see [Assembly versioning](versioning.md). diff --git a/docs/standard/assembly/manifest.md b/docs/standard/assembly/manifest.md index 3a68452f42a22..9d94f660debfb 100644 --- a/docs/standard/assembly/manifest.md +++ b/docs/standard/assembly/manifest.md @@ -2,7 +2,7 @@ title: "Assembly manifest" description: A .NET assembly manifest specifies its version requirements, security identity, and scope of the assembly and information to resolve references. ms.date: "08/20/2019" -helpviewer_keywords: +helpviewer_keywords: - "assembly manifest" - "dynamic assemblies, assembly manifest" - "metadata, assembly manifest" @@ -12,42 +12,42 @@ ms.assetid: 8e40fab9-549d-4731-aec2-ffa47a382de0 --- # Assembly manifest -Every assembly, whether static or dynamic, contains a collection of data that describes how the elements in the assembly relate to each other. The assembly manifest contains this assembly metadata. An assembly manifest contains all the metadata needed to specify the assembly's version requirements and security identity, and all metadata needed to define the scope of the assembly and resolve references to resources and classes. The assembly manifest can be stored in either a PE file (an *.exe* or *.dll*) with Microsoft intermediate language (MSIL) code or in a standalone PE file that contains only assembly manifest information. - - The following illustration shows the different ways the manifest can be stored. - - ![Diagram that shows the manifest in a single-file assembly and multifile assembly configuration.](./media/manifest/assembly-types-diagram.gif) - - For an assembly with one associated file, the manifest is incorporated into the PE file to form a single-file assembly. You can create a multifile assembly with a standalone manifest file or with the manifest incorporated into one of the PE files in the assembly. - - Each assembly's manifest performs the following functions: - -- Enumerates the files that make up the assembly. - -- Governs how references to the assembly's types and resources map to the files that contain their declarations and implementations. - -- Enumerates other assemblies on which the assembly depends. - -- Provides a level of indirection between consumers of the assembly and the assembly's implementation details. - -- Renders the assembly self-describing. - -## Assembly manifest contents - - The following table shows the information contained in the assembly manifest. The first four items: assembly name, version number, culture, and strong name information make up the assembly's identity. - -|Information|Description| -|-----------------|-----------------| -|Assembly name|A text string specifying the assembly's name.| -|Version number|A major and minor version number, and a revision and build number. The common language runtime uses these numbers to enforce version policy.| -|Culture|Information on the culture or language the assembly supports. This information should be used only to designate an assembly as a satellite assembly containing culture- or language-specific information. (An assembly with culture information is automatically assumed to be a satellite assembly.)| -|Strong name information|The public key from the publisher if the assembly has been given a strong name.| -|List of all files in the assembly|A hash of each file contained in the assembly and a file name. Note that all files that make up the assembly must be in the same directory as the file containing the assembly manifest.| -|Type reference information|Information used by the runtime to map a type reference to the file that contains its declaration and implementation. This is used for types that are exported from the assembly.| -|Information on referenced assemblies|A list of other assemblies that are statically referenced by the assembly. Each reference includes the dependent assembly's name, assembly metadata (version, culture, operating system, and so on), and public key, if the assembly is strong named.| - - You can add or change some information in the assembly manifest by using assembly attributes in your code. You can change version information and informational attributes, including Trademark, Copyright, Product, Company, and Informational Version. For a complete list of assembly attributes, see [Set assembly attributes](set-attributes.md). - +Every assembly, whether static or dynamic, contains a collection of data that describes how the elements in the assembly relate to each other. The assembly manifest contains this assembly metadata. An assembly manifest contains all the metadata needed to specify the assembly's version requirements and security identity, and all metadata needed to define the scope of the assembly and resolve references to resources and classes. The assembly manifest can be stored in either a PE file (an *.exe* or *.dll*) with common intermediate language (CIL) code or in a standalone PE file that contains only assembly manifest information. + + The following illustration shows the different ways the manifest can be stored. + + ![Diagram that shows the manifest in a single-file assembly and multifile assembly configuration.](./media/manifest/assembly-types-diagram.gif) + + For an assembly with one associated file, the manifest is incorporated into the PE file to form a single-file assembly. You can create a multifile assembly with a standalone manifest file or with the manifest incorporated into one of the PE files in the assembly. + + Each assembly's manifest performs the following functions: + +- Enumerates the files that make up the assembly. + +- Governs how references to the assembly's types and resources map to the files that contain their declarations and implementations. + +- Enumerates other assemblies on which the assembly depends. + +- Provides a level of indirection between consumers of the assembly and the assembly's implementation details. + +- Renders the assembly self-describing. + +## Assembly manifest contents + + The following table shows the information contained in the assembly manifest. The first four items: assembly name, version number, culture, and strong name information make up the assembly's identity. + +|Information|Description| +|-----------------|-----------------| +|Assembly name|A text string specifying the assembly's name.| +|Version number|A major and minor version number, and a revision and build number. The common language runtime uses these numbers to enforce version policy.| +|Culture|Information on the culture or language the assembly supports. This information should be used only to designate an assembly as a satellite assembly containing culture- or language-specific information. (An assembly with culture information is automatically assumed to be a satellite assembly.)| +|Strong name information|The public key from the publisher if the assembly has been given a strong name.| +|List of all files in the assembly|A hash of each file contained in the assembly and a file name. Note that all files that make up the assembly must be in the same directory as the file containing the assembly manifest.| +|Type reference information|Information used by the runtime to map a type reference to the file that contains its declaration and implementation. This is used for types that are exported from the assembly.| +|Information on referenced assemblies|A list of other assemblies that are statically referenced by the assembly. Each reference includes the dependent assembly's name, assembly metadata (version, culture, operating system, and so on), and public key, if the assembly is strong named.| + + You can add or change some information in the assembly manifest by using assembly attributes in your code. You can change version information and informational attributes, including Trademark, Copyright, Product, Company, and Informational Version. For a complete list of assembly attributes, see [Set assembly attributes](set-attributes.md). + ## See also - [Assembly contents](contents.md) diff --git a/docs/standard/assembly/view-contents.md b/docs/standard/assembly/view-contents.md index a1aa615047270..ad4b040cdb025 100644 --- a/docs/standard/assembly/view-contents.md +++ b/docs/standard/assembly/view-contents.md @@ -18,7 +18,7 @@ dev_langs: --- # How to: View assembly contents -You can use the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) to view Microsoft intermediate language (MSIL) information in a file. If the file being examined is an assembly, this information can include the assembly's attributes and references to other modules and assemblies. This information can be helpful in determining whether a file is an assembly or part of an assembly and whether the file has references to other modules or assemblies. +You can use the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) to view common intermediate language (CIL) information in a file. If the file being examined is an assembly, this information can include the assembly's attributes and references to other modules and assemblies. This information can be helpful in determining whether a file is an assembly or part of an assembly and whether the file has references to other modules or assemblies. To display the contents of an assembly using *Ildasm.exe*, enter **ildasm \** at a command prompt. For example, the following command disassembles the *Hello.exe* assembly. @@ -26,7 +26,7 @@ To display the contents of an assembly using *Ildasm.exe*, enter **ildasm \. +The common language runtime allows you to add keyword-like descriptive declarations, called attributes, to annotate programming elements such as types, fields, methods, and properties. When you compile your code for the runtime, it is converted into common intermediate language (CIL) and placed inside a portable executable (PE) file along with metadata generated by the compiler. Attributes allow you to place extra descriptive information into metadata that can be extracted using runtime reflection services. The compiler creates attributes when you declare instances of special classes that derive from . .NET uses attributes for a variety of reasons and to address a number of issues. Attributes describe how to serialize data, specify characteristics that are used to enforce security, and limit optimizations by the just-in-time (JIT) compiler so the code remains easy to debug. Attributes can also record the name of a file or the author of code, or control the visibility of controls and members during forms development. diff --git a/docs/standard/base-types/best-practices-regex.md b/docs/standard/base-types/best-practices-regex.md index bb0b741aee6e5..7526ebd9f5b13 100644 --- a/docs/standard/base-types/best-practices-regex.md +++ b/docs/standard/base-types/best-practices-regex.md @@ -76,7 +76,7 @@ The particular way in which you call regular expression matching methods can aff ### Static regular expressions -Static regular expression methods are recommended as an alternative to repeatedly instantiating a regular expression object with the same regular expression. Unlike regular expression patterns used by regular expression objects, either the operation codes or the compiled Microsoft intermediate language (MSIL) from patterns used in static method calls is cached internally by the regular expression engine. +Static regular expression methods are recommended as an alternative to repeatedly instantiating a regular expression object with the same regular expression. Unlike regular expression patterns used by regular expression objects, either the operation codes or the compiled common intermediate language (CIL) from patterns used in static method calls is cached internally by the regular expression engine. For example, an event handler frequently calls another method to validate user input. This example is reflected in the following code, in which a control's event is used to call a method named `IsValidCurrency`, which checks whether the user has entered a currency symbol followed by at least one decimal digit. @@ -108,9 +108,9 @@ The regular expression `\p{Sc}+\s*\d+` that's used in this example verifies that ### Interpreted vs. compiled regular expressions -Regular expression patterns that aren't bound to the regular expression engine through the specification of the option are interpreted. When a regular expression object is instantiated, the regular expression engine converts the regular expression to a set of operation codes. When an instance method is called, the operation codes are converted to MSIL and executed by the JIT compiler. Similarly, when a static regular expression method is called and the regular expression can't be found in the cache, the regular expression engine converts the regular expression to a set of operation codes and stores them in the cache. It then converts these operation codes to MSIL so that the JIT compiler can execute them. Interpreted regular expressions reduce startup time at the cost of slower execution time. Because of this process, they're best used when the regular expression is used in a small number of method calls, or if the exact number of calls to regular expression methods is unknown but is expected to be small. As the number of method calls increases, the performance gain from reduced startup time is outstripped by the slower execution speed. +Regular expression patterns that aren't bound to the regular expression engine through the specification of the option are interpreted. When a regular expression object is instantiated, the regular expression engine converts the regular expression to a set of operation codes. When an instance method is called, the operation codes are converted to CIL and executed by the JIT compiler. Similarly, when a static regular expression method is called and the regular expression can't be found in the cache, the regular expression engine converts the regular expression to a set of operation codes and stores them in the cache. It then converts these operation codes to CIL so that the JIT compiler can execute them. Interpreted regular expressions reduce startup time at the cost of slower execution time. Because of this process, they're best used when the regular expression is used in a small number of method calls, or if the exact number of calls to regular expression methods is unknown but is expected to be small. As the number of method calls increases, the performance gain from reduced startup time is outstripped by the slower execution speed. -Regular expression patterns that are bound to the regular expression engine through the specification of the option are compiled. Therefore, when a regular expression object is instantiated, or when a static regular expression method is called and the regular expression can't be found in the cache, the regular expression engine converts the regular expression to an intermediary set of operation codes. These codes are then converted to MSIL. When a method is called, the JIT compiler executes the MSIL. In contrast to interpreted regular expressions, compiled regular expressions increase startup time but execute individual pattern-matching methods faster. As a result, the performance benefit that results from compiling the regular expression increases in proportion to the number of regular expression methods called. +Regular expression patterns that are bound to the regular expression engine through the specification of the option are compiled. Therefore, when a regular expression object is instantiated, or when a static regular expression method is called and the regular expression can't be found in the cache, the regular expression engine converts the regular expression to an intermediary set of operation codes. These codes are then converted to CIL. When a method is called, the JIT compiler executes the CIL. In contrast to interpreted regular expressions, compiled regular expressions increase startup time but execute individual pattern-matching methods faster. As a result, the performance benefit that results from compiling the regular expression increases in proportion to the number of regular expression methods called. To summarize, we recommend that you use interpreted regular expressions when you call regular expression methods with a specific regular expression relatively infrequently. You should use compiled regular expressions when you call regular expression methods with a specific regular expression relatively frequently. It's difficult to determine the exact threshold at which the slower execution speeds of interpreted regular expressions outweigh gains from their reduced startup time, or the threshold at which the slower startup times of compiled regular expressions outweigh gains from their faster execution speeds. It depends on various factors, including the complexity of the regular expression and the specific data that it processes. To determine whether interpreted or compiled regular expressions offer the best performance for your particular application scenario, you can use the class to compare their execution times. diff --git a/docs/standard/base-types/common-type-system.md b/docs/standard/base-types/common-type-system.md index e088be594ed5f..3abdb4d940c40 100644 --- a/docs/standard/base-types/common-type-system.md +++ b/docs/standard/base-types/common-type-system.md @@ -228,7 +228,7 @@ A property names a value or state of the type and defines methods for getting or [!code-csharp[Conceptual.Types.Members.Properties#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.types.members.properties/cs/example.cs#1)] [!code-vb[Conceptual.Types.Members.Properties#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.types.members.properties/vb/example.vb#1)] -In addition to including the property itself, the Microsoft intermediate language (MSIL) for a type that contains a readable property includes a `get_`*propertyname* method, and the MSIL for a type that contains a writable property includes a `set_`*propertyname* method. +In addition to including the property itself, the common intermediate language (CIL) for a type that contains a readable property includes a `get_`*propertyname* method, and the CIL for a type that contains a writable property includes a `set_`*propertyname* method. ### Methods diff --git a/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md b/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md index cf01c8f254dc5..a0dec2ad85f23 100644 --- a/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md +++ b/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md @@ -3,7 +3,7 @@ title: "Compilation and Reuse in Regular Expressions" description: "Learn about compilation and reuse in Regular Expressions." ms.topic: conceptual ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "parsing text with regular expressions, compilation" - "searching with regular expressions, compilation" - ".NET regular expressions, engines" @@ -16,30 +16,30 @@ ms.assetid: 182ec76d-5a01-4d73-996c-0b0d14fcea18 --- # Compilation and Reuse in Regular Expressions -You can optimize the performance of applications that make extensive use of regular expressions by understanding how the regular expression engine compiles expressions and by understanding how regular expressions are cached. This topic discusses both compilation and caching. - -## Compiled Regular Expressions +You can optimize the performance of applications that make extensive use of regular expressions by understanding how the regular expression engine compiles expressions and by understanding how regular expressions are cached. This topic discusses both compilation and caching. - By default, the regular expression engine compiles a regular expression to a sequence of internal instructions (these are high-level codes that are different from Microsoft intermediate language, or MSIL). When the engine executes a regular expression, it interprets the internal codes. - - If a object is constructed with the option, it compiles the regular expression to explicit MSIL code instead of high-level regular expression internal instructions. This allows .NET's just-in-time (JIT) compiler to convert the expression to native machine code for higher performance. The cost of constructing the object may be higher, but the cost of performing matches with it is likely to be much smaller. +## Compiled Regular Expressions - An alternative is to use precompiled regular expressions. You can compile all of your expressions into a reusable DLL by using the method. This avoids the need to compile at run time while still benefiting from the speed of compiled regular expressions. - -## The Regular Expressions Cache + By default, the regular expression engine compiles a regular expression to a sequence of internal instructions (these are high-level codes that are different from common intermediate language, or CIL). When the engine executes a regular expression, it interprets the internal codes. + + If a object is constructed with the option, it compiles the regular expression to explicit CIL code instead of high-level regular expression internal instructions. This allows .NET's just-in-time (JIT) compiler to convert the expression to native machine code for higher performance. The cost of constructing the object may be higher, but the cost of performing matches with it is likely to be much smaller. + + An alternative is to use precompiled regular expressions. You can compile all of your expressions into a reusable DLL by using the method. This avoids the need to compile at run time while still benefiting from the speed of compiled regular expressions. + +## The Regular Expressions Cache + + To improve performance, the regular expression engine maintains an application-wide cache of compiled regular expressions. The cache stores regular expression patterns that are used only in static method calls. (Regular expression patterns supplied to instance methods are not cached.) This avoids the need to reparse an expression into high-level byte code each time it is used. + + The maximum number of cached regular expressions is determined by the value of the `static` (`Shared` in Visual Basic) property. By default, the regular expression engine caches up to 15 compiled regular expressions. If the number of compiled regular expressions exceeds the cache size, the least recently used regular expression is discarded and the new regular expression is cached. + + Your application can reuse regular expressions in one of the following two ways: - To improve performance, the regular expression engine maintains an application-wide cache of compiled regular expressions. The cache stores regular expression patterns that are used only in static method calls. (Regular expression patterns supplied to instance methods are not cached.) This avoids the need to reparse an expression into high-level byte code each time it is used. - - The maximum number of cached regular expressions is determined by the value of the `static` (`Shared` in Visual Basic) property. By default, the regular expression engine caches up to 15 compiled regular expressions. If the number of compiled regular expressions exceeds the cache size, the least recently used regular expression is discarded and the new regular expression is cached. - - Your application can reuse regular expressions in one of the following two ways: - - By using a static method of the object to define the regular expression. If you're using a regular expression pattern that has already been defined by another static method call, the regular expression engine will try to retrieve it from the cache. If it's not available in the cache, the engine will compile the regular expression and add it to the cache. - -- By reusing an existing object as long as its regular expression pattern is needed. - - Because of the overhead of object instantiation and regular expression compilation, creating and rapidly destroying numerous objects is a very expensive process. For applications that use a large number of different regular expressions, you can optimize performance by using calls to static `Regex` methods and possibly by increasing the size of the regular expression cache. - + +- By reusing an existing object as long as its regular expression pattern is needed. + + Because of the overhead of object instantiation and regular expression compilation, creating and rapidly destroying numerous objects is a very expensive process. For applications that use a large number of different regular expressions, you can optimize performance by using calls to static `Regex` methods and possibly by increasing the size of the regular expression cache. + ## See also - [.NET Regular Expressions](regular-expressions.md) diff --git a/docs/standard/base-types/regular-expression-options.md b/docs/standard/base-types/regular-expression-options.md index 34b9fcb164a2d..d6c0114499668 100644 --- a/docs/standard/base-types/regular-expression-options.md +++ b/docs/standard/base-types/regular-expression-options.md @@ -230,7 +230,7 @@ Finally, you can use the inline group element `(?n:)` to suppress automatic capt By default, regular expressions in .NET are interpreted. When a object is instantiated or a static method is called, the regular expression pattern is parsed into a set of custom opcodes, and an interpreter uses these opcodes to run the regular expression. This involves a tradeoff: The cost of initializing the regular expression engine is minimized at the expense of run-time performance. -You can use compiled instead of interpreted regular expressions by using the option. In this case, when a pattern is passed to the regular expression engine, it is parsed into a set of opcodes and then converted to Microsoft intermediate language (MSIL), which can be passed directly to the common language runtime. Compiled regular expressions maximize run-time performance at the expense of initialization time. +You can use compiled instead of interpreted regular expressions by using the option. In this case, when a pattern is passed to the regular expression engine, it is parsed into a set of opcodes and then converted to common intermediate language (CIL), which can be passed directly to the common language runtime. Compiled regular expressions maximize run-time performance at the expense of initialization time. > [!NOTE] > A regular expression can be compiled only by supplying the value to the `options` parameter of a class constructor or a static pattern-matching method. It is not available as an inline option. diff --git a/docs/standard/data/xml/script-blocks-using-msxsl-script.md b/docs/standard/data/xml/script-blocks-using-msxsl-script.md index a29f728b6af06..ffe21e97d91ad 100644 --- a/docs/standard/data/xml/script-blocks-using-msxsl-script.md +++ b/docs/standard/data/xml/script-blocks-using-msxsl-script.md @@ -2,7 +2,7 @@ description: "Learn more about: Script Blocks Using msxsl:script" title: "Script Blocks Using msxsl:script" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: fde6f43f-c594-486f-abcb-2211197fae20 @@ -12,147 +12,147 @@ ms.assetid: fde6f43f-c594-486f-abcb-2211197fae20 > [!NOTE] > Script blocks are supported only in .NET Framework. They are _not_ supported on .NET Core or .NET 5 or later. -The class supports embedded scripts using the `msxsl:script` element. When the style sheet is loaded, any defined functions are compiled to Microsoft intermediate language (MSIL) by the Code Document Object Model (CodeDOM) and are executed during run time. The assembly generated from the embedded script block is separate than the assembly generated for the style sheet. - -## Enable XSLT Script +The class supports embedded scripts using the `msxsl:script` element. When the style sheet is loaded, any defined functions are compiled to common intermediate language (CIL) by the Code Document Object Model (CodeDOM) and are executed during run time. The assembly generated from the embedded script block is separate than the assembly generated for the style sheet. + +## Enable XSLT Script + + Support for embedded scripts is an optional XSLT setting on the class. Script support is disabled by default. To enable script support, create an object with the property set to `true` and pass the object to the method. - Support for embedded scripts is an optional XSLT setting on the class. Script support is disabled by default. To enable script support, create an object with the property set to `true` and pass the object to the method. - > [!NOTE] -> XSLT scripting should be enabled only if you require script support and you are working in a fully trusted environment. - -## msxsl:script Element Definition - - The `msxsl:script` element is a Microsoft extension to the XSLT 1.0 recommendation and has the following definition: - -```xml - -``` - - The `msxsl` prefix is bound to the `urn:schemas-microsoft-com:xslt` namespace URI. The style sheet must include the `xmlns:msxsl=urn:schemas-microsoft-com:xslt` namespace declaration. - - The `language` attribute is optional. Its value is the code language of the embedded code block. The language is mapped to the appropriate CodeDOM compiler using the method. The class can support any Microsoft .NET language, assuming the appropriate provider is installed on the machine and is registered in the system.codedom section of the machine.config file. If a `language` attribute is not specified, the language defaults to JScript. The language name is not case-sensitive so 'JavaScript' and 'javascript' are equivalent. - - The `implements-prefix` attribute is mandatory. This attribute is used to declare a namespace and associate it with the script block. The value of this attribute is the prefix that represents the namespace. This prefix can be defined somewhere in a style sheet. - +> XSLT scripting should be enabled only if you require script support and you are working in a fully trusted environment. + +## msxsl:script Element Definition + + The `msxsl:script` element is a Microsoft extension to the XSLT 1.0 recommendation and has the following definition: + +```xml + +``` + + The `msxsl` prefix is bound to the `urn:schemas-microsoft-com:xslt` namespace URI. The style sheet must include the `xmlns:msxsl=urn:schemas-microsoft-com:xslt` namespace declaration. + + The `language` attribute is optional. Its value is the code language of the embedded code block. The language is mapped to the appropriate CodeDOM compiler using the method. The class can support any Microsoft .NET language, assuming the appropriate provider is installed on the machine and is registered in the system.codedom section of the machine.config file. If a `language` attribute is not specified, the language defaults to JScript. The language name is not case-sensitive so 'JavaScript' and 'javascript' are equivalent. + + The `implements-prefix` attribute is mandatory. This attribute is used to declare a namespace and associate it with the script block. The value of this attribute is the prefix that represents the namespace. This prefix can be defined somewhere in a style sheet. + > [!NOTE] -> When using the `msxsl:script` element, we strongly recommend that the script, regardless of language, be placed inside a CDATA section. Because the script can contain operators, identifiers, or delimiters for a given language, if it is not contained within a CDATA section, it has the potential of being misinterpreted as XML. The following XML shows a template of the CDATA section where code can be placed. - -```xml - - - -``` - -## Script Functions - - Functions can be declared within the `msxsl:script` element. When a function is declared, it is contained in a script block. Style sheets can contain multiple script blocks, each operating independent of the other. That means that if you are executing inside a script block, you cannot call a function that you defined in another script block unless it is declared to have the same namespace and the same scripting language. Because each script block can be in its own language, and the block is parsed according to the grammar rules of that language parser we recommend that you use the correct syntax for the language in use. For example, if you are in a Microsoft C# script block, use the C# comment syntax. - - The supplied arguments and return values to the function can be of any type. Because the W3C XPath types are a subset of the common language runtime (CLR) types, type conversion takes place on types that are not considered to be an XPath type. The following table shows the corresponding W3C types and the equivalent CLR type. - -|W3C type|CLR type| -|--------------|--------------| -|`String`|| -|`Boolean`|| -|`Number`|| -|`Result Tree Fragment`|| -|`Node Set`|| - - CLR numeric types are converted to . The type is converted to . types are converted to . **XPathNavigator[]** is converted to . - - All other types throw an error. - -### Importing Namespaces and Assemblies - - The class predefines a set of assemblies and namespaces that are supported by default by the `msxsl:script` element. However, you can use classes and members belonging to a namespace that is not on the predefined list by importing the assembly and namespace in `msxsl:script` block. - -#### Assemblies - - The following two assemblies are referenced by default: - -- System.dll - -- System.Xml.dll - -- Microsoft.VisualBasic.dll (when the script language is VB) - - You can import the additional assemblies using the `msxsl:assembly` element. This includes the assembly when the style sheet is compiled. The `msxsl:assembly` element has the following definition: - -```xml - - - - - -``` - - The `name` attribute contains the name of the assembly and the `href` attribute contains the path to the assembly. The assembly name can be a full name, such as "System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089", or a short name, such as "System.Web". - -#### Namespaces - - The following namespaces are included by default: - -- System - -- System.Collection - -- System.Text - -- System.Text.RegularExpressions - -- System.Xml - -- System.Xml.Xsl - -- System.Xml.XPath - -- Microsoft.VisualBasic (when the script language is VB) - - You can add support for additional namespaces using the `namespace` attribute. The attribute value is the name of the namespace. - -```xml - - - - -``` - -## Example - - The following example uses an embedded script to calculate the circumference of a circle given its radius. - +> When using the `msxsl:script` element, we strongly recommend that the script, regardless of language, be placed inside a CDATA section. Because the script can contain operators, identifiers, or delimiters for a given language, if it is not contained within a CDATA section, it has the potential of being misinterpreted as XML. The following XML shows a template of the CDATA section where code can be placed. + +```xml + + + +``` + +## Script Functions + + Functions can be declared within the `msxsl:script` element. When a function is declared, it is contained in a script block. Style sheets can contain multiple script blocks, each operating independent of the other. That means that if you are executing inside a script block, you cannot call a function that you defined in another script block unless it is declared to have the same namespace and the same scripting language. Because each script block can be in its own language, and the block is parsed according to the grammar rules of that language parser we recommend that you use the correct syntax for the language in use. For example, if you are in a Microsoft C# script block, use the C# comment syntax. + + The supplied arguments and return values to the function can be of any type. Because the W3C XPath types are a subset of the common language runtime (CLR) types, type conversion takes place on types that are not considered to be an XPath type. The following table shows the corresponding W3C types and the equivalent CLR type. + +|W3C type|CLR type| +|--------------|--------------| +|`String`|| +|`Boolean`|| +|`Number`|| +|`Result Tree Fragment`|| +|`Node Set`|| + + CLR numeric types are converted to . The type is converted to . types are converted to . **XPathNavigator[]** is converted to . + + All other types throw an error. + +### Importing Namespaces and Assemblies + + The class predefines a set of assemblies and namespaces that are supported by default by the `msxsl:script` element. However, you can use classes and members belonging to a namespace that is not on the predefined list by importing the assembly and namespace in `msxsl:script` block. + +#### Assemblies + + The following two assemblies are referenced by default: + +- System.dll + +- System.Xml.dll + +- Microsoft.VisualBasic.dll (when the script language is VB) + + You can import the additional assemblies using the `msxsl:assembly` element. This includes the assembly when the style sheet is compiled. The `msxsl:assembly` element has the following definition: + +```xml + + + + + +``` + + The `name` attribute contains the name of the assembly and the `href` attribute contains the path to the assembly. The assembly name can be a full name, such as "System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089", or a short name, such as "System.Web". + +#### Namespaces + + The following namespaces are included by default: + +- System + +- System.Collection + +- System.Text + +- System.Text.RegularExpressions + +- System.Xml + +- System.Xml.Xsl + +- System.Xml.XPath + +- Microsoft.VisualBasic (when the script language is VB) + + You can add support for additional namespaces using the `namespace` attribute. The attribute value is the name of the namespace. + +```xml + + + + +``` + +## Example + + The following example uses an embedded script to calculate the circumference of a circle given its radius. + [!code-csharp[XSLT_Script#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XSLT_Script/CS/xslt_script.cs#1)] - [!code-vb[XSLT_Script#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XSLT_Script/VB/xslt_script.vb#1)] - -#### number.xml - - [!code-xml[XSLT_Script#2](../../../../samples/snippets/xml/VS_Snippets_Data/XSLT_Script/XML/number.xml#2)] - -#### calc.xsl - - [!code-xml[XSLT_Script#3](../../../../samples/snippets/xml/VS_Snippets_Data/XSLT_Script/XML/calc.xsl#3)] - -### Output - -```xml - - - 12 - 75.36 - - - 37.5 - 235.5 - - -``` - + [!code-vb[XSLT_Script#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XSLT_Script/VB/xslt_script.vb#1)] + +#### number.xml + + [!code-xml[XSLT_Script#2](../../../../samples/snippets/xml/VS_Snippets_Data/XSLT_Script/XML/number.xml#2)] + +#### calc.xsl + + [!code-xml[XSLT_Script#3](../../../../samples/snippets/xml/VS_Snippets_Data/XSLT_Script/XML/calc.xsl#3)] + +### Output + +```xml + + + 12 + 75.36 + + + 37.5 + 235.5 + + +``` + ## See also - [XSLT Transformations](xslt-transformations.md) diff --git a/docs/standard/generics/index.md b/docs/standard/generics/index.md index 0d55c8d23ded6..d2b9f72c077d4 100644 --- a/docs/standard/generics/index.md +++ b/docs/standard/generics/index.md @@ -124,7 +124,7 @@ The namespace provides generic i Support for generics has been added to the namespace for examining generic types and generic methods, to for emitting dynamic assemblies that contain generic types and methods, and to for generating source graphs that include generics. -The common language runtime provides new opcodes and prefixes to support generic types in Microsoft intermediate language (MSIL), including , , , , and . +The common language runtime provides new opcodes and prefixes to support generic types in common intermediate language (CIL), including , , , , and . Visual C++, C#, and Visual Basic all provide full support for defining and using generics. For more information about language support, see [Generic Types in Visual Basic](../../visual-basic/programming-guide/language-features/data-types/generic-types.md), [Introduction to Generics](../../csharp/fundamentals/types/generics.md), and [Overview of Generics in Visual C++](/cpp/windows/overview-of-generics-in-visual-cpp). diff --git a/docs/standard/managed-code.md b/docs/standard/managed-code.md index 59b1686777cc8..98fdf4e2bd6cd 100644 --- a/docs/standard/managed-code.md +++ b/docs/standard/managed-code.md @@ -18,9 +18,9 @@ Managed code is written in one of the high-level languages that can be run on to What is "Intermediate Language" (or IL for short)? It is a product of compilation of code written in high-level .NET languages. Once you compile your code written in one of these languages, you will get a binary that is made out of IL. It is important to note that the IL is independent from any specific language that runs on top of the runtime; there is even a separate specification for it that you can read if you're so inclined. -Once you produce IL from your high-level code, you will most likely want to run it. This is where the CLR takes over and starts the process of **Just-In-Time** compiling, or **JIT-ing** your code from IL to machine code that can actually be run on a CPU. In this way, the CLR knows exactly what your code is doing and can effectively _manage_ it. +Once you produce IL from your high-level code, you will most likely want to run it. This is where the CLR takes over and starts the process of **Just-In-Time** compiling, or **JIT-ing** your code from IL to machine code that can actually be run on a CPU. In this way, the CLR knows exactly what your code is doing and can effectively *manage* it. -Intermediate Language is sometimes also called Common Intermediate Language (CIL) or Microsoft Intermediate Language (MSIL). +Intermediate Language is sometimes also called Common Intermediate Language (CIL) or common intermediate language (CIL). ## Unmanaged code interoperability diff --git a/docs/standard/metadata-and-self-describing-components.md b/docs/standard/metadata-and-self-describing-components.md index 2dbb04453f153..8d3f7c36bf9fc 100644 --- a/docs/standard/metadata-and-self-describing-components.md +++ b/docs/standard/metadata-and-self-describing-components.md @@ -20,7 +20,7 @@ ms.assetid: 3dd13c5d-a508-455b-8dce-0a852882a5a7 In the past, a software component (.exe or .dll) that was written in one language could not easily use a software component that was written in another language. COM provided a step towards solving this problem. .NET makes component interoperation even easier by allowing compilers to emit additional declarative information into all modules and assemblies. This information, called metadata, helps components to interact seamlessly. - Metadata is binary information describing your program that is stored either in a common language runtime portable executable (PE) file or in memory. When you compile your code into a PE file, metadata is inserted into one portion of the file, and your code is converted to Microsoft intermediate language (MSIL) and inserted into another portion of the file. Every type and member that is defined and referenced in a module or assembly is described within metadata. When code is executed, the runtime loads metadata into memory and references it to discover information about your code's classes, members, inheritance, and so on. + Metadata is binary information describing your program that is stored either in a common language runtime portable executable (PE) file or in memory. When you compile your code into a PE file, metadata is inserted into one portion of the file, and your code is converted to common intermediate language (CIL) and inserted into another portion of the file. Every type and member that is defined and referenced in a module or assembly is described within metadata. When code is executed, the runtime loads metadata into memory and references it to discover information about your code's classes, members, inheritance, and so on. Metadata describes every type and member defined in your code in a language-neutral manner. Metadata stores the following information: @@ -62,7 +62,7 @@ Metadata is the key to a simpler programming model, and eliminates the need for ## Metadata and the PE File Structure -Metadata is stored in one section of a .NET portable executable (PE) file, while Microsoft intermediate language (MSIL) is stored in another section of the PE file. The metadata portion of the file contains a series of table and heap data structures. The MSIL portion contains MSIL and metadata tokens that reference the metadata portion of the PE file. You might encounter metadata tokens when you use tools such as the [MSIL Disassembler (Ildasm.exe)](../framework/tools/ildasm-exe-il-disassembler.md) to view your code's MSIL, for example. +Metadata is stored in one section of a .NET portable executable (PE) file, while common intermediate language (CIL) is stored in another section of the PE file. The metadata portion of the file contains a series of table and heap data structures. The CIL portion contains CIL and metadata tokens that reference the metadata portion of the PE file. You might encounter metadata tokens when you use tools such as the [IL Disassembler (Ildasm.exe)](../framework/tools/ildasm-exe-il-disassembler.md) to view your code's CIL, for example. ### Metadata Tables and Heaps @@ -72,9 +72,9 @@ Metadata also stores information in four heap structures: string, blob, user str ### Metadata Tokens -Each row of each metadata table is uniquely identified in the MSIL portion of the PE file by a metadata token. Metadata tokens are conceptually similar to pointers, persisted in MSIL, that reference a particular metadata table. +Each row of each metadata table is uniquely identified in the CIL portion of the PE file by a metadata token. Metadata tokens are conceptually similar to pointers, persisted in CIL, that reference a particular metadata table. -A metadata token is a four-byte number. The top byte denotes the metadata table to which a particular token refers (method, type, and so on). The remaining three bytes specify the row in the metadata table that corresponds to the programming element being described. If you define a method in C# and compile it into a PE file, the following metadata token might exist in the MSIL portion of the PE file: +A metadata token is a four-byte number. The top byte denotes the metadata table to which a particular token refers (method, type, and so on). The remaining three bytes specify the row in the metadata table that corresponds to the programming element being described. If you define a method in C# and compile it into a PE file, the following metadata token might exist in the CIL portion of the PE file: `0x06000004` @@ -87,7 +87,7 @@ When a program is compiled for the common language runtime, it is converted to a |PE section|Contents of PE section| |----------------|----------------------------| |PE header|The index of the PE file's main sections and the address of the entry point.

The runtime uses this information to identify the file as a PE file and to determine where execution starts when loading the program into memory.| -|MSIL instructions|The Microsoft intermediate language instructions (MSIL) that make up your code. Many MSIL instructions are accompanied by metadata tokens.| +|CIL instructions|The Microsoft intermediate language instructions (CIL) that make up your code. Many CIL instructions are accompanied by metadata tokens.| |Metadata|Metadata tables and heaps. The runtime uses this section to record information about every type and member in your code. This section also includes custom attributes and security information.| ## Run-Time Use of Metadata @@ -126,9 +126,9 @@ public class MyApp } ``` -When the code runs, the runtime loads the module into memory and consults the metadata for this class. Once loaded, the runtime performs extensive analysis of the method's Microsoft intermediate language (MSIL) stream to convert it to fast native machine instructions. The runtime uses a just-in-time (JIT) compiler to convert the MSIL instructions to native machine code one method at a time as needed. +When the code runs, the runtime loads the module into memory and consults the metadata for this class. Once loaded, the runtime performs extensive analysis of the method's common intermediate language (CIL) stream to convert it to fast native machine instructions. The runtime uses a just-in-time (JIT) compiler to convert the CIL instructions to native machine code one method at a time as needed. -The following example shows part of the MSIL produced from the previous code's `Main` function. You can view the MSIL and metadata from any .NET application using the [MSIL Disassembler (Ildasm.exe)](../framework/tools/ildasm-exe-il-disassembler.md). +The following example shows part of the CIL produced from the previous code's `Main` function. You can view the CIL and metadata from any .NET application using the [CIL Disassembler (Ildasm.exe)](../framework/tools/ildasm-exe-il-disassembler.md). ```console .entrypoint @@ -147,7 +147,7 @@ IL_000c: ldloc.1 IL_000d: call int32 ConsoleApplication.MyApp::Add(int32,int32) /* 06000003 */ ``` -The JIT compiler reads the MSIL for the whole method, analyzes it thoroughly, and generates efficient native instructions for the method. At `IL_000d`, a metadata token for the `Add` method (`/*` `06000003 */`) is encountered and the runtime uses the token to consult the third row of the **MethodDef** table. +The JIT compiler reads the CIL for the whole method, analyzes it thoroughly, and generates efficient native instructions for the method. At `IL_000d`, a metadata token for the `Add` method (`/*` `06000003 */`) is encountered and the runtime uses the token to consult the third row of the **MethodDef** table. The following table shows part of the **MethodDef** table referenced by the metadata token that describes the `Add` method. While other metadata tables exist in this assembly and have their own unique values, only this table is discussed. @@ -157,8 +157,8 @@ The following table shows part of the **MethodDef** table referenced by the meta |2|0x00002058|IL

Managed|Public

Static

ReuseSlot|Main|String| |3|0x0000208c|IL

Managed|Public

Static

ReuseSlot|Add|int, int, int| -Each column of the table contains important information about your code. The **RVA** column allows the runtime to calculate the starting memory address of the MSIL that defines this method. The **ImplFlags** and **Flags** columns contain bitmasks that describe the method (for example, whether the method is public or private). The **Name** column indexes the name of the method from the string heap. The **Signature** column indexes the definition of the method's signature in the blob heap. +Each column of the table contains important information about your code. The **RVA** column allows the runtime to calculate the starting memory address of the CIL that defines this method. The **ImplFlags** and **Flags** columns contain bitmasks that describe the method (for example, whether the method is public or private). The **Name** column indexes the name of the method from the string heap. The **Signature** column indexes the definition of the method's signature in the blob heap. -The runtime calculates the desired offset address from the **RVA** column in the third row and returns this address to the JIT compiler, which then proceeds to the new address. The JIT compiler continues to process MSIL at the new address until it encounters another metadata token and the process is repeated. +The runtime calculates the desired offset address from the **RVA** column in the third row and returns this address to the JIT compiler, which then proceeds to the new address. The JIT compiler continues to process CIL at the new address until it encounters another metadata token and the process is repeated. Using metadata, the runtime has access to all the information it needs to load your code and process it into native machine instructions. In this manner, metadata enables self-describing files and, together with the common type system, cross-language inheritance. diff --git a/docs/standard/security/key-security-concepts.md b/docs/standard/security/key-security-concepts.md index e8851fb1488b6..bef72483aa4b4 100644 --- a/docs/standard/security/key-security-concepts.md +++ b/docs/standard/security/key-security-concepts.md @@ -2,11 +2,11 @@ description: "Learn more about: Key Security Concepts" title: "Key Security Concepts" ms.date: 07/15/2020 -dev_langs: +dev_langs: - "csharp" - "vb" - "cpp" -helpviewer_keywords: +helpviewer_keywords: - "unauthorized access" - "permissions [.NET]" - "security [.NET], about security" @@ -19,54 +19,54 @@ ms.assetid: 3cfced4f-ea02-4e66-ae98-d69286363e98 > > For information about ASP.NET Core, see [Overview of ASP.NET Core Security](/aspnet/core/security/). -.NET offers role-based security to help address security concerns about mobile code and to provide support that enables components to determine what users are authorized to do. - -## Type safety and security - -Type-safe code accesses only the memory locations it is authorized to access. (For this discussion, type safety specifically refers to memory type safety and should not be confused with type safety in a broader respect.) For example, type-safe code cannot read values from another object's private fields. It accesses types only in well-defined, allowable ways. - -During just-in-time (JIT) compilation, an optional verification process examines the metadata and Microsoft intermediate language (MSIL) of a method to be JIT-compiled into native machine code to verify that they are type safe. This process is skipped if the code has permission to bypass verification. For more information about verification, see [Managed Execution Process](../managed-execution-process.md). - -Although verification of type safety is not mandatory to run managed code, type safety plays a crucial role in assembly isolation and security enforcement. When code is type safe, the common language runtime can completely isolate assemblies from each other. This isolation helps ensure that assemblies cannot adversely affect each other and it increases application reliability. Type-safe components can execute safely in the same process even if they are trusted at different levels. When code is not type safe, unwanted side effects can occur. For example, the runtime cannot prevent managed code from calling into native (unmanaged) code and performing malicious operations. When code is type safe, the runtime's security enforcement mechanism ensures that it does not access native code unless it has permission to do so. All code that is not type safe must have been granted with the passed enum member to run. - -[!INCLUDE [cas-deprecated](../../../includes/cas-deprecated.md)] - -## Principal - -A principal represents the identity and role of a user and acts on the user's behalf. Role-based security in .NET supports three kinds of principals: - -- Generic principals represent users and roles that exist independent of Windows users and roles. - -- Windows principals represent Windows users and their roles (or their Windows groups). A Windows principal can impersonate another user, which means that the principal can access a resource on a user's behalf while presenting the identity that belongs to that user. - -- Custom principals can be defined by an application in any way that is needed for that particular application. They can extend the basic notion of the principal's identity and roles. - -For more information, see [Principal and Identity Objects](principal-and-identity-objects.md). - -## Authentication - -Authentication is the process of discovering and verifying the identity of a principal by examining the user's credentials and validating those credentials against some authority. The information obtained during authentication is directly usable by your code. You can also use .NET role-based security to authenticate the current user and to determine whether to allow that principal to access your code. See the overloads of the method for examples of how to authenticate the principal for specific roles. For example, you can use the overload to determine if the current user is a member of the Administrators group. - -A variety of authentication mechanisms are used today, many of which can be used with .NET role-based security. Some of the most commonly used mechanisms are basic, digest, Passport, operating system (such as NTLM or Kerberos), or application-defined mechanisms. - -### Example - -The following example requires that the active principal be an administrator. The `name` parameter is `null`, which allows any user who is an administrator to pass the demand. - +.NET offers role-based security to help address security concerns about mobile code and to provide support that enables components to determine what users are authorized to do. + +## Type safety and security + +Type-safe code accesses only the memory locations it is authorized to access. (For this discussion, type safety specifically refers to memory type safety and should not be confused with type safety in a broader respect.) For example, type-safe code cannot read values from another object's private fields. It accesses types only in well-defined, allowable ways. + +During just-in-time (JIT) compilation, an optional verification process examines the metadata and common intermediate language (CIL) of a method to be JIT-compiled into native machine code to verify that they are type safe. This process is skipped if the code has permission to bypass verification. For more information about verification, see [Managed Execution Process](../managed-execution-process.md). + +Although verification of type safety is not mandatory to run managed code, type safety plays a crucial role in assembly isolation and security enforcement. When code is type safe, the common language runtime can completely isolate assemblies from each other. This isolation helps ensure that assemblies cannot adversely affect each other and it increases application reliability. Type-safe components can execute safely in the same process even if they are trusted at different levels. When code is not type safe, unwanted side effects can occur. For example, the runtime cannot prevent managed code from calling into native (unmanaged) code and performing malicious operations. When code is type safe, the runtime's security enforcement mechanism ensures that it does not access native code unless it has permission to do so. All code that is not type safe must have been granted with the passed enum member to run. + +[!INCLUDE [cas-deprecated](../../../includes/cas-deprecated.md)] + +## Principal + +A principal represents the identity and role of a user and acts on the user's behalf. Role-based security in .NET supports three kinds of principals: + +- Generic principals represent users and roles that exist independent of Windows users and roles. + +- Windows principals represent Windows users and their roles (or their Windows groups). A Windows principal can impersonate another user, which means that the principal can access a resource on a user's behalf while presenting the identity that belongs to that user. + +- Custom principals can be defined by an application in any way that is needed for that particular application. They can extend the basic notion of the principal's identity and roles. + +For more information, see [Principal and Identity Objects](principal-and-identity-objects.md). + +## Authentication + +Authentication is the process of discovering and verifying the identity of a principal by examining the user's credentials and validating those credentials against some authority. The information obtained during authentication is directly usable by your code. You can also use .NET role-based security to authenticate the current user and to determine whether to allow that principal to access your code. See the overloads of the method for examples of how to authenticate the principal for specific roles. For example, you can use the overload to determine if the current user is a member of the Administrators group. + +A variety of authentication mechanisms are used today, many of which can be used with .NET role-based security. Some of the most commonly used mechanisms are basic, digest, Passport, operating system (such as NTLM or Kerberos), or application-defined mechanisms. + +### Example + +The following example requires that the active principal be an administrator. The `name` parameter is `null`, which allows any user who is an administrator to pass the demand. + > [!NOTE] -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that requires you to be an administrator, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. - +> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that requires you to be an administrator, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. + [!code-cpp[Classic PrincipalPermission Example#1](../../../samples/snippets/cpp/VS_Snippets_CLR_Classic/classic PrincipalPermission Example/CPP/source.cpp#1)] [!code-csharp[Classic PrincipalPermission Example#1](../../../samples/snippets/csharp/VS_Snippets_CLR_Classic/classic PrincipalPermission Example/CS/source.cs#1)] - [!code-vb[Classic PrincipalPermission Example#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PrincipalPermission Example/VB/source.vb#1)] - - The following example demonstrates how to determine the identity of the principal and the roles available to the principal. An application of this example might be to confirm that the current user is in a role you allow for using your application. - + [!code-vb[Classic PrincipalPermission Example#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PrincipalPermission Example/VB/source.vb#1)] + + The following example demonstrates how to determine the identity of the principal and the roles available to the principal. An application of this example might be to confirm that the current user is in a role you allow for using your application. + [!code-cpp[System.Security.Principal.WindowsBuiltInRole Example#1](../../../samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/CPP/source.cpp#1)] [!code-csharp[System.Security.Principal.WindowsBuiltInRole Example#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/CS/source.cs#1)] - [!code-vb[System.Security.Principal.WindowsBuiltInRole Example#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/VB/source.vb#1)] - -## Authorization + [!code-vb[System.Security.Principal.WindowsBuiltInRole Example#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/VB/source.vb#1)] + +## Authorization Authorization is the process of determining whether a principal is allowed to perform a requested action. Authorization occurs after authentication and uses information about the principal's identity and roles to determine what resources the principal can access. You can use .NET role-based security to implement authorization. diff --git a/docs/visual-basic/programming-guide/concepts/expression-trees/index.md b/docs/visual-basic/programming-guide/concepts/expression-trees/index.md index 4f3f2a29b5c48..61f1a1df5ad5f 100644 --- a/docs/visual-basic/programming-guide/concepts/expression-trees/index.md +++ b/docs/visual-basic/programming-guide/concepts/expression-trees/index.md @@ -6,142 +6,142 @@ ms.assetid: 8bbbb02d-7ffc-476b-8c25-118d82bf5d46 --- # Expression Trees (Visual Basic) -Expression trees represent code in a tree-like data structure, where each node is an expression, for example, a method call or a binary operation such as `x < y`. - - You can compile and run code represented by expression trees. This enables dynamic modification of executable code, the execution of LINQ queries in various databases, and the creation of dynamic queries. For more information about expression trees in LINQ, see [How to: Use Expression Trees to Build Dynamic Queries (Visual Basic)](how-to-use-expression-trees-to-build-dynamic-queries.md). - - Expression trees are also used in the dynamic language runtime (DLR) to provide interoperability between dynamic languages and the .NET Framework and to enable compiler writers to emit expression trees instead of Microsoft intermediate language (MSIL). For more information about the DLR, see [Dynamic Language Runtime Overview](../../../../framework/reflection-and-codedom/dynamic-language-runtime-overview.md). - - You can have the C# or Visual Basic compiler create an expression tree for you based on an anonymous lambda expression, or you can create expression trees manually by using the namespace. - -## Creating Expression Trees from Lambda Expressions - - When a lambda expression is assigned to a variable of type , the compiler emits code to build an expression tree that represents the lambda expression. - - The Visual Basic compiler can generate expression trees only from expression lambdas (or single-line lambdas). It cannot parse statement lambdas (or multi-line lambdas). For more information about lambda expressions in Visual Basic, see [Lambda Expressions](../../language-features/procedures/lambda-expressions.md). - - The following code examples demonstrate how to have the Visual Basic compiler create an expression tree that represents the lambda expression `Function(num) num < 5`. - -```vb -Dim lambda As Expression(Of Func(Of Integer, Boolean)) = - Function(num) num < 5 -``` - -## Creating Expression Trees by Using the API - - To create expression trees by using the API, use the class. This class contains static factory methods that create expression tree nodes of specific types, for example, , which represents a variable or parameter, or , which represents a method call. , , and the other expression-specific types are also defined in the namespace. These types derive from the abstract type . - - The following code example demonstrates how to create an expression tree that represents the lambda expression `Function(num) num < 5` by using the API. - -```vb -' Import the following namespace to your project: System.Linq.Expressions - -' Manually build the expression tree for the lambda expression num => num < 5. -Dim numParam As ParameterExpression = Expression.Parameter(GetType(Integer), "num") -Dim five As ConstantExpression = Expression.Constant(5, GetType(Integer)) -Dim numLessThanFive As BinaryExpression = Expression.LessThan(numParam, five) -Dim lambda1 As Expression(Of Func(Of Integer, Boolean)) = - Expression.Lambda(Of Func(Of Integer, Boolean))( - numLessThanFive, - New ParameterExpression() {numParam}) -``` - - In .NET Framework 4 or later, the expression trees API also supports assignments and control flow expressions such as loops, conditional blocks, and `try-catch` blocks. By using the API, you can create expression trees that are more complex than those that can be created from lambda expressions by the Visual Basic compiler. The following example demonstrates how to create an expression tree that calculates the factorial of a number. - -```vb -' Creating a parameter expression. -Dim value As ParameterExpression = - Expression.Parameter(GetType(Integer), "value") - +Expression trees represent code in a tree-like data structure, where each node is an expression, for example, a method call or a binary operation such as `x < y`. + + You can compile and run code represented by expression trees. This enables dynamic modification of executable code, the execution of LINQ queries in various databases, and the creation of dynamic queries. For more information about expression trees in LINQ, see [How to: Use Expression Trees to Build Dynamic Queries (Visual Basic)](how-to-use-expression-trees-to-build-dynamic-queries.md). + + Expression trees are also used in the dynamic language runtime (DLR) to provide interoperability between dynamic languages and the .NET Framework and to enable compiler writers to emit expression trees instead of common intermediate language (CIL). For more information about the DLR, see [Dynamic Language Runtime Overview](../../../../framework/reflection-and-codedom/dynamic-language-runtime-overview.md). + + You can have the C# or Visual Basic compiler create an expression tree for you based on an anonymous lambda expression, or you can create expression trees manually by using the namespace. + +## Creating Expression Trees from Lambda Expressions + + When a lambda expression is assigned to a variable of type , the compiler emits code to build an expression tree that represents the lambda expression. + + The Visual Basic compiler can generate expression trees only from expression lambdas (or single-line lambdas). It cannot parse statement lambdas (or multi-line lambdas). For more information about lambda expressions in Visual Basic, see [Lambda Expressions](../../language-features/procedures/lambda-expressions.md). + + The following code examples demonstrate how to have the Visual Basic compiler create an expression tree that represents the lambda expression `Function(num) num < 5`. + +```vb +Dim lambda As Expression(Of Func(Of Integer, Boolean)) = + Function(num) num < 5 +``` + +## Creating Expression Trees by Using the API + + To create expression trees by using the API, use the class. This class contains static factory methods that create expression tree nodes of specific types, for example, , which represents a variable or parameter, or , which represents a method call. , , and the other expression-specific types are also defined in the namespace. These types derive from the abstract type . + + The following code example demonstrates how to create an expression tree that represents the lambda expression `Function(num) num < 5` by using the API. + +```vb +' Import the following namespace to your project: System.Linq.Expressions + +' Manually build the expression tree for the lambda expression num => num < 5. +Dim numParam As ParameterExpression = Expression.Parameter(GetType(Integer), "num") +Dim five As ConstantExpression = Expression.Constant(5, GetType(Integer)) +Dim numLessThanFive As BinaryExpression = Expression.LessThan(numParam, five) +Dim lambda1 As Expression(Of Func(Of Integer, Boolean)) = + Expression.Lambda(Of Func(Of Integer, Boolean))( + numLessThanFive, + New ParameterExpression() {numParam}) +``` + + In .NET Framework 4 or later, the expression trees API also supports assignments and control flow expressions such as loops, conditional blocks, and `try-catch` blocks. By using the API, you can create expression trees that are more complex than those that can be created from lambda expressions by the Visual Basic compiler. The following example demonstrates how to create an expression tree that calculates the factorial of a number. + +```vb +' Creating a parameter expression. +Dim value As ParameterExpression = + Expression.Parameter(GetType(Integer), "value") + ' Creating an expression to hold a local variable. -Dim result As ParameterExpression = - Expression.Parameter(GetType(Integer), "result") - -' Creating a label to jump to from a loop. -Dim label As LabelTarget = Expression.Label(GetType(Integer)) - -' Creating a method body. -Dim block As BlockExpression = Expression.Block( - New ParameterExpression() {result}, - Expression.Assign(result, Expression.Constant(1)), - Expression.Loop( - Expression.IfThenElse( - Expression.GreaterThan(value, Expression.Constant(1)), - Expression.MultiplyAssign(result, - Expression.PostDecrementAssign(value)), - Expression.Break(label, result) - ), - label - ) -) - -' Compile an expression tree and return a delegate. -Dim factorial As Integer = - Expression.Lambda(Of Func(Of Integer, Integer))(block, value).Compile()(5) - -Console.WriteLine(factorial) -' Prints 120. +Dim result As ParameterExpression = + Expression.Parameter(GetType(Integer), "result") + +' Creating a label to jump to from a loop. +Dim label As LabelTarget = Expression.Label(GetType(Integer)) + +' Creating a method body. +Dim block As BlockExpression = Expression.Block( + New ParameterExpression() {result}, + Expression.Assign(result, Expression.Constant(1)), + Expression.Loop( + Expression.IfThenElse( + Expression.GreaterThan(value, Expression.Constant(1)), + Expression.MultiplyAssign(result, + Expression.PostDecrementAssign(value)), + Expression.Break(label, result) + ), + label + ) +) + +' Compile an expression tree and return a delegate. +Dim factorial As Integer = + Expression.Lambda(Of Func(Of Integer, Integer))(block, value).Compile()(5) + +Console.WriteLine(factorial) +' Prints 120. ``` For more information, see [Generating Dynamic Methods with Expression Trees in Visual Studio 2010](https://devblogs.microsoft.com/csharpfaq/generating-dynamic-methods-with-expression-trees-in-visual-studio-2010/), which also applies to later versions of Visual Studio. - -## Parsing Expression Trees - - The following code example demonstrates how the expression tree that represents the lambda expression `Function(num) num < 5` can be decomposed into its parts. - -```vb -' Import the following namespace to your project: System.Linq.Expressions - -' Create an expression tree. -Dim exprTree As Expression(Of Func(Of Integer, Boolean)) = Function(num) num < 5 - -' Decompose the expression tree. -Dim param As ParameterExpression = exprTree.Parameters(0) -Dim operation As BinaryExpression = exprTree.Body -Dim left As ParameterExpression = operation.Left -Dim right As ConstantExpression = operation.Right - -Console.WriteLine(String.Format("Decomposed expression: {0} => {1} {2} {3}", - param.Name, left.Name, operation.NodeType, right.Value)) - -' This code produces the following output: -' -' Decomposed expression: num => num LessThan 5 -``` - -## Immutability of Expression Trees - - Expression trees should be immutable. This means that if you want to modify an expression tree, you must construct a new expression tree by copying the existing one and replacing nodes in it. You can use an expression tree visitor to traverse the existing expression tree. For more information, see [How to: Modify Expression Trees (Visual Basic)](how-to-modify-expression-trees.md). - -## Compiling Expression Trees - - The type provides the method that compiles the code represented by an expression tree into an executable delegate. - - The following code example demonstrates how to compile an expression tree and run the resulting code. - -```vb -' Creating an expression tree. -Dim expr As Expression(Of Func(Of Integer, Boolean)) = - Function(num) num < 5 - -' Compiling the expression tree into a delegate. -Dim result As Func(Of Integer, Boolean) = expr.Compile() - -' Invoking the delegate and writing the result to the console. -Console.WriteLine(result(4)) - -' Prints True. - -' You can also use simplified syntax -' to compile and run an expression tree. -' The following line can replace two previous statements. -Console.WriteLine(expr.Compile()(4)) - -' Also prints True. -``` - - For more information, see [How to: Execute Expression Trees (Visual Basic)](how-to-execute-expression-trees.md). - + +## Parsing Expression Trees + + The following code example demonstrates how the expression tree that represents the lambda expression `Function(num) num < 5` can be decomposed into its parts. + +```vb +' Import the following namespace to your project: System.Linq.Expressions + +' Create an expression tree. +Dim exprTree As Expression(Of Func(Of Integer, Boolean)) = Function(num) num < 5 + +' Decompose the expression tree. +Dim param As ParameterExpression = exprTree.Parameters(0) +Dim operation As BinaryExpression = exprTree.Body +Dim left As ParameterExpression = operation.Left +Dim right As ConstantExpression = operation.Right + +Console.WriteLine(String.Format("Decomposed expression: {0} => {1} {2} {3}", + param.Name, left.Name, operation.NodeType, right.Value)) + +' This code produces the following output: +' +' Decomposed expression: num => num LessThan 5 +``` + +## Immutability of Expression Trees + + Expression trees should be immutable. This means that if you want to modify an expression tree, you must construct a new expression tree by copying the existing one and replacing nodes in it. You can use an expression tree visitor to traverse the existing expression tree. For more information, see [How to: Modify Expression Trees (Visual Basic)](how-to-modify-expression-trees.md). + +## Compiling Expression Trees + + The type provides the method that compiles the code represented by an expression tree into an executable delegate. + + The following code example demonstrates how to compile an expression tree and run the resulting code. + +```vb +' Creating an expression tree. +Dim expr As Expression(Of Func(Of Integer, Boolean)) = + Function(num) num < 5 + +' Compiling the expression tree into a delegate. +Dim result As Func(Of Integer, Boolean) = expr.Compile() + +' Invoking the delegate and writing the result to the console. +Console.WriteLine(result(4)) + +' Prints True. + +' You can also use simplified syntax +' to compile and run an expression tree. +' The following line can replace two previous statements. +Console.WriteLine(expr.Compile()(4)) + +' Also prints True. +``` + + For more information, see [How to: Execute Expression Trees (Visual Basic)](how-to-execute-expression-trees.md). + ## See also - diff --git a/docs/visual-basic/programming-guide/concepts/iterators.md b/docs/visual-basic/programming-guide/concepts/iterators.md index 2a39e1981a200..7df1b2887452c 100644 --- a/docs/visual-basic/programming-guide/concepts/iterators.md +++ b/docs/visual-basic/programming-guide/concepts/iterators.md @@ -410,7 +410,7 @@ In Visual Basic, "Yield" is not a reserved word and has special meaning only whe Although you write an iterator as a method, the compiler translates it into a nested class that is, in effect, a state machine. This class keeps track of the position of the iterator as long the `For Each...Next` loop in the client code continues. -To see what the compiler does, you can use the Ildasm.exe tool to view the Microsoft intermediate language code that is generated for an iterator method. +To see what the compiler does, you can use the Ildasm.exe tool to view the common intermediate language code that is generated for an iterator method. When you create an iterator for a [class](../../language-reference/statements/class-statement.md) or [struct](../../language-reference/statements/structure-statement.md), you do not have to implement the whole interface. When the compiler detects the iterator, it automatically generates the `Current`, `MoveNext`, and `Dispose` methods of the or interface. diff --git a/docs/visual-basic/reference/command-line-compiler/keycontainer.md b/docs/visual-basic/reference/command-line-compiler/keycontainer.md index fa7e540955229..97c8fb8a4f14b 100644 --- a/docs/visual-basic/reference/command-line-compiler/keycontainer.md +++ b/docs/visual-basic/reference/command-line-compiler/keycontainer.md @@ -2,7 +2,7 @@ description: "Learn more about: -keycontainer" title: "-keycontainer" ms.date: 03/10/2018 -helpviewer_keywords: +helpviewer_keywords: - "-keycontainer compiler option [Visual Basic]" - "keycontainer compiler option [Visual Basic]" - "/keycontainer compiler option [Visual Basic]" @@ -10,43 +10,43 @@ ms.assetid: 6a9bc861-1752-4db1-9f64-b5252f0482cc --- # -keycontainer -Specifies a key container name for a key pair to give an assembly a strong name. - -## Syntax - -```console --keycontainer:container -``` - -## Arguments - -|Term|Definition| -|---|---| -|`container`|Required. Container file that contains the key. Enclose the file name in quotation marks ("") if the name contains a space.| - -## Remarks - - The compiler creates the sharable component by inserting a public key into the assembly manifest and by signing the final assembly with the private key. To generate a key file, type `sn -k file` at the command line. The `-i` option installs the key pair into a container. For more information, see [Sn.exe (Strong Name Tool)](../../../framework/tools/sn-exe-strong-name-tool.md)). - - If you compile with `-target:module`, the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly with [-addmodule](addmodule.md). - - You can also specify this option as a custom attribute () in the source code for any Microsoft intermediate language (MSIL) module. - - You can also pass your encryption information to the compiler with [-keyfile](keyfile.md). Use [-delaysign](delaysign.md) if you want a partially signed assembly. - - See [Creating and Using Strong-Named Assemblies](../../../standard/assembly/create-use-strong-named.md) for more information on signing an assembly. - +Specifies a key container name for a key pair to give an assembly a strong name. + +## Syntax + +```console +-keycontainer:container +``` + +## Arguments + +|Term|Definition| +|---|---| +|`container`|Required. Container file that contains the key. Enclose the file name in quotation marks ("") if the name contains a space.| + +## Remarks + + The compiler creates the sharable component by inserting a public key into the assembly manifest and by signing the final assembly with the private key. To generate a key file, type `sn -k file` at the command line. The `-i` option installs the key pair into a container. For more information, see [Sn.exe (Strong Name Tool)](../../../framework/tools/sn-exe-strong-name-tool.md)). + + If you compile with `-target:module`, the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly with [-addmodule](addmodule.md). + + You can also specify this option as a custom attribute () in the source code for any common intermediate language (CIL) module. + + You can also pass your encryption information to the compiler with [-keyfile](keyfile.md). Use [-delaysign](delaysign.md) if you want a partially signed assembly. + + See [Creating and Using Strong-Named Assemblies](../../../standard/assembly/create-use-strong-named.md) for more information on signing an assembly. + > [!NOTE] -> The `-keycontainer` option is not available from within the Visual Studio development environment; it is available only when compiling from the command line. - -## Example - - The following code compiles source file `Input.vb` and specifies a key container. - -```console -vbc -keycontainer:key1 input.vb -``` - +> The `-keycontainer` option is not available from within the Visual Studio development environment; it is available only when compiling from the command line. + +## Example + + The following code compiles source file `Input.vb` and specifies a key container. + +```console +vbc -keycontainer:key1 input.vb +``` + ## See also - [Assemblies in .NET](../../../standard/assembly/index.md) diff --git a/docs/visual-basic/reference/command-line-compiler/keyfile.md b/docs/visual-basic/reference/command-line-compiler/keyfile.md index c79d77232e553..eb2fa73e94ee2 100644 --- a/docs/visual-basic/reference/command-line-compiler/keyfile.md +++ b/docs/visual-basic/reference/command-line-compiler/keyfile.md @@ -10,35 +10,35 @@ ms.assetid: ffa82a4b-517a-4c6c-9889-5bae7b534bb8 --- # -keyfile -Specifies a file containing a key or key pair to give an assembly a strong name. - -## Syntax - +Specifies a file containing a key or key pair to give an assembly a strong name. + +## Syntax + ```console --keyfile:file -``` - -## Arguments - - `file` - Required. File that contains the key. If the file name contains a space, enclose the name in quotation marks (" "). - -## Remarks - - The compiler inserts the public key into the assembly manifest and then signs the final assembly with the private key. To generate a key file, type `sn -k file` at the command line. For more information, see [Sn.exe (Strong Name Tool)](../../../framework/tools/sn-exe-strong-name-tool.md)). - - If you compile with `-target:module`, the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly with [-addmodule](addmodule.md). - - You can also pass your encryption information to the compiler with [-keycontainer](keycontainer.md). Use [-delaysign](delaysign.md) if you want a partially signed assembly. - - You can also specify this option as a custom attribute () in the source code for any Microsoft intermediate language module. - - In case both `-keyfile` and [-keycontainer](keycontainer.md) are specified (either by command-line option or by custom attribute) in the same compilation, the compiler first tries the key container. If that succeeds, then the assembly is signed with the information in the key container. If the compiler does not find the key container, it tries the file specified with `-keyfile`. If this succeeds, the assembly is signed with the information in the key file, and the key information is installed in the key container (similar to `sn -i`) so that on the next compilation, the key container will be valid. - - Note that a key file might contain only the public key. - - See [Creating and Using Strong-Named Assemblies](../../../standard/assembly/create-use-strong-named.md) for more information on signing an assembly. - +-keyfile:file +``` + +## Arguments + + `file` + Required. File that contains the key. If the file name contains a space, enclose the name in quotation marks (" "). + +## Remarks + + The compiler inserts the public key into the assembly manifest and then signs the final assembly with the private key. To generate a key file, type `sn -k file` at the command line. For more information, see [Sn.exe (Strong Name Tool)](../../../framework/tools/sn-exe-strong-name-tool.md)). + + If you compile with `-target:module`, the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly with [-addmodule](addmodule.md). + + You can also pass your encryption information to the compiler with [-keycontainer](keycontainer.md). Use [-delaysign](delaysign.md) if you want a partially signed assembly. + + You can also specify this option as a custom attribute () in the source code for any common intermediate language module. + + In case both `-keyfile` and [-keycontainer](keycontainer.md) are specified (either by command-line option or by custom attribute) in the same compilation, the compiler first tries the key container. If that succeeds, then the assembly is signed with the information in the key container. If the compiler does not find the key container, it tries the file specified with `-keyfile`. If this succeeds, the assembly is signed with the information in the key file, and the key information is installed in the key container (similar to `sn -i`) so that on the next compilation, the key container will be valid. + + Note that a key file might contain only the public key. + + See [Creating and Using Strong-Named Assemblies](../../../standard/assembly/create-use-strong-named.md) for more information on signing an assembly. + > [!NOTE] > The `-keyfile` option is not available from within the Visual Studio development environment; it is available only when compiling from the command line. diff --git a/docs/visual-basic/reference/command-line-compiler/rootnamespace.md b/docs/visual-basic/reference/command-line-compiler/rootnamespace.md index 1fcf15cb24b32..11b72c43004ac 100644 --- a/docs/visual-basic/reference/command-line-compiler/rootnamespace.md +++ b/docs/visual-basic/reference/command-line-compiler/rootnamespace.md @@ -2,10 +2,10 @@ description: "Learn more about: -rootnamespace" title: "-rootnamespace" ms.date: 03/13/2018 -f1_keywords: +f1_keywords: - "/rootnamespace" - "rootnamespace" -helpviewer_keywords: +helpviewer_keywords: - "/rootnamespace compiler option [Visual Basic]" - "-rootnamespace compiler option [Visual Basic]" - "rootnamespace compiler option [Visual Basic]" @@ -13,38 +13,38 @@ ms.assetid: e9245edf-6bef-420d-a7c7-324117752783 --- # -rootnamespace -Specifies a namespace for all type declarations. - -## Syntax - -```console --rootnamespace:namespace -``` - -## Arguments - -|Term|Definition| -|---|---| -|`namespace`|The name of the namespace in which to enclose all type declarations for the current project.| - -## Remarks - - If you use the Visual Studio executable file (Devenv.exe) to compile a project created in the Visual Studio integrated development environment, use `-rootnamespace` to specify the value of the property. See [Devenv Command Line Switches](/visualstudio/ide/reference/devenv-command-line-switches) for more information. - - Use the common language runtime MSIL Disassembler (`Ildasm.exe`) to view the namespace names in your output file. - -|To set -rootnamespace in the Visual Studio integrated development environment| -|---| -|1. Have a project selected in **Solution Explorer**. On the **Project** menu, click **Properties**.
2. Click the **Application** tab.
3. Modify the value in the **Root Namespace** box.| - -## Example - - The following code compiles `In.vb` and encloses all type declarations in the namespace `mynamespace`. - +Specifies a namespace for all type declarations. + +## Syntax + ```console -vbc -rootnamespace:mynamespace in.vb -``` - +-rootnamespace:namespace +``` + +## Arguments + +|Term|Definition| +|---|---| +|`namespace`|The name of the namespace in which to enclose all type declarations for the current project.| + +## Remarks + + If you use the Visual Studio executable file (Devenv.exe) to compile a project created in the Visual Studio integrated development environment, use `-rootnamespace` to specify the value of the property. See [Devenv Command Line Switches](/visualstudio/ide/reference/devenv-command-line-switches) for more information. + + Use the IL Disassembler tool (`Ildasm.exe`) to view the namespace names in your output file. + +|To set -rootnamespace in the Visual Studio integrated development environment| +|---| +|1. Have a project selected in **Solution Explorer**. On the **Project** menu, click **Properties**.
2. Click the **Application** tab.
3. Modify the value in the **Root Namespace** box.| + +## Example + + The following code compiles `In.vb` and encloses all type declarations in the namespace `mynamespace`. + +```console +vbc -rootnamespace:mynamespace in.vb +``` + ## See also - [Visual Basic Command-Line Compiler](index.md)