Exposing Types to Visual Designers

Visual Studio must have access to class and type definitions at design time in order to display a visual designer. Classes are loaded from a predefined set of assemblies that include the complete dependency set of the current project (references plus their dependencies). It may also be necessary for visual designers to access classes and types that are defined in files generated by custom tools.

The Visual Basic and Visual C# project systems provide support for accessing generated classes and types through temporary portable executable files (temporary PEs). Any file generated by a custom tool can be compiled into a temporary assembly so that types may be loaded from those assemblies and exposed to designers. The output of each custom tool is compiled into a separate temporary PE, and the success or failure of this temporary compilation depends only on whether or not the generated file can be compiled. Even though a project may not build as a whole, individual temporary PEs may still be available to designers.

The project system provides full support for tracking changes to the output file of a custom tool, provided that these changes are the result of running the custom tool. Each time the custom tool is run, a new temporary PE is generated, and appropriate notifications are sent to designers.

Custom tools that take advantage of temporary PE support must follow the following rules:

• GeneratesDesignTimeSource must be set to 1 in the registry.

  No program executable file compilation takes place without this setting.

• The generated code must be in the same language as the global project setting.

  The temporary PE is compiled regardless of what the custom tool reports as the requested extension in DefaultExtension provided that GeneratesDesignTimeSource is set to 1 in the registry. The extension does not need to be .vb, .cs, or .jsl; it can be any extension.

• The code generated by the custom tool must be valid, and it must compile on its own using only the set of references present in the project at the time Generate finishes executing.

  When a temporary PE is compiled, the only source file provided to the compiler is the custom tool output. Therefore, a custom tool that uses a temporary PE must generate output files that can be compiled independently of other files in the project.

See Also

Concepts

Introduction to the BuildManager Object

Implementing Single-File Generators

Determining the Default Namespace

Registering Single File Generators