Export (0) Print
Expand All

BuildProvider Class

Defines a set of properties and methods for generating source code within the ASP.NET build environment. This class is abstract.

Namespace:  System.Web.Compilation
Assembly:  System.Web (in System.Web.dll)

public abstract class BuildProvider

The BuildProvider type exposes the following members.

  NameDescription
Protected methodBuildProviderInitializes a new instance of the BuildProvider class.
Top

  NameDescription
Public propertyCodeCompilerTypeRepresents the compiler type used by a build provider to generate source code for a custom file type.
Protected propertyReferencedAssembliesRepresents the assemblies to compile with the source generated by the build provider.
Protected propertyVirtualPathRepresents the file to be built by this build provider implementation.
Public propertyVirtualPathDependenciesRepresents a collection of virtual paths that must be built before the build provider generates code.
Top

  NameDescription
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGenerateCodeGenerates source code for the virtual path of the build provider, and adds the source code to a specified assembly builder.
Protected methodGetCodeCompileUnitRepresents the container for the generated CodeDOM graph.
Public methodGetCustomStringInfrastructure. Generates a string to be persisted in the compiled assembly.
Protected methodGetDefaultCompilerTypeReturns the compiler settings for the default language in the application.
Protected methodGetDefaultCompilerTypeForLanguageReturns the compiler settings for the build provider based on the specified language.
Public methodGetGeneratedTypeReturns a type generated by the build provider from the virtual path.
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetResultFlagsReturns a value indicating actions required when a virtual path is built.
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected methodOpenReader()Opens a text reader for reading from the virtual path of the current build provider object.
Protected methodOpenReader(String)Opens a text reader for reading from a specified virtual path.
Protected methodOpenStream()Opens a stream for reading the virtual path of the current build provider object.
Protected methodOpenStream(String)Opens a stream for reading from a specified virtual path.
Public methodProcessCompileErrorsWhen overridden in a derived class, enables you to review compiler error messages so that you can modify them to provide more information.
Public methodStatic memberRegisterBuildProviderRegisters a build provider.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

The ASP.NET build environment uses BuildProvider objects to generate source code for different file types within an application. Classes derived from BuildProvider predominantly provide source code for files, Web pages, resources, and other custom items.

Typically, you do not create an instance of the BuildProvider class directly. Instead, you implement a class that derives from BuildProvider, and configure the BuildProvider implementation for use within the ASP.NET build environment.

Instances of the BuildProvider class are used with AssemblyBuilder objects to build one or more files into a compiled assembly. A BuildProvider instance generates source code in the appropriate language for individual files, and the AssemblyBuilder object combines the source contributed by each BuildProvider instance into a single assembly.

The ASP.NET build environment uses instances of the BuildProvider class to build files within an application. The VirtualPath property of the BuildProvider class indicates the path of the file to be built. The file extension of each file within an application is mapped to a corresponding build provider. The ASP.NET build environment initializes a BuildProvider instance for each file based on the file extension, and uses the BuildProvider methods to generate source code for the file. The ASP.NET build environment passes an AssemblyBuilder object based on the preferred compiler language and the context of the file to the BuildProvider methods when building an assembly from one or more files, so that the BuildProvider instance can contribute source code for its file to the overall assembly.

To define custom build actions for a file type within an ASP.NET application, you must derive a class from BuildProvider, implement members within the derived class for building the file type, and configure the build provider for the corresponding file extension within the application configuration file.

The add element specifies the file extension for supported files, and whether the build provider supports code files, Web files, resource files or all files. Use the type attribute to specify the fully qualified type name of the build provider implementation. Use the BuildProviderAppliesToAttribute class to specify whether the build provider applies to files in the App_Code directory, to files in a Web content directory, to global or local resources, or to all files. Use the extension attribute to specify the file extension used to identify files that the BuildProvider class supports. Use the BuildProviderCollection class to examine build providers in a configuration file. For more information about configuring a build provider, see buildProviders Element for compilation (ASP.NET Settings Schema).

To implement a build provider that generates source code for a custom file type, derive a class from BuildProvider, and override the GenerateCode method to generate source code for the supported file type. The generated source is added to the AssemblyBuilder object in the form of a CodeDOM graph, or as content that represents a physical source code file. If the build provider requires a specific programming language, override the CodeCompilerType property to return a CompilerType object for the supported programming language. If the build provider does not require a specific programming language, do not override the CodeCompilerType property; use the base class implementation, which indicates that the build provider can use any .NET Framework language, such as Visual Basic or C#.

To implement a build provider that generates source code for Web content, derive a class from BuildProvider and override the GetGeneratedType method to return the Type for the class generated by BuildProvider. Override the GenerateCode method to generate source code for the type provided by the supported file.

NoteNote

Adding a customized BuildProvider class to the Web.config file works in an ASP.NET Web site but does not work in an ASP.NET Web application project. In a Web application project, the code that is generated by the BuildProvider class cannot be included in the application. For more information, see ASP.NET Web Application Project Precompilation Overview.

TopicLocation
How To: Secure an ASP.NET Application on a Shared ServerBuilding ASP .NET Web Applications
How To: Secure an ASP.NET Application on a Shared ServerBuilding ASP .NET Web Applications

The following code example illustrates a simple build provider implementation, inheriting from the abstract BuildProvider base class. The build provider overrides the CodeCompilerType, GetGeneratedType, and GenerateCode members of the base class. The example does not include the implementation of the SampleClassGenerator class. For more information, see the CodeCompileUnit class overview.

using System;
using System.Collections;
using System.IO;
using System.Text;
using System.Web;
using System.Web.Compilation;
using System.CodeDom.Compiler;
using System.CodeDom;
using System.Security;
using System.Security.Permissions;

// Define a simple build provider implementation.
[PermissionSet(SecurityAction.Demand, Unrestricted = true)]
public class SampleBuildProvider : BuildProvider
{
    // Define an internal member for the compiler type. 
    protected CompilerType _compilerType = null;

    public SampleBuildProvider()
    {
        _compilerType = GetDefaultCompilerTypeForLanguage("C#");
    }

    // Return the internal CompilerType member  
    // defined in this implementation. 
    public override CompilerType CodeCompilerType
    {
        get { return _compilerType; }
    }


    // Define the build provider implementation of the GenerateCode method. 
    public override void GenerateCode(AssemblyBuilder assemBuilder)
    {
        // Generate a code compile unit, and add it to 
        // the assembly builder.

        TextWriter tw = assemBuilder.CreateCodeFile(this);
        if (tw != null)
        {
            try
            {
                // Generate the code compile unit from the virtual path.
                CodeCompileUnit compileUnit = SampleClassGenerator.BuildCompileUnitFromPath(VirtualPath);

                // Generate the source for the code compile unit,  
                // and write it to a file specified by the assembly builder.
                CodeDomProvider provider = assemBuilder.CodeDomProvider;
                provider.GenerateCodeFromCompileUnit(compileUnit, tw, null);
            }
            finally
            {
                tw.Close();
            }
        }
    }

    public override System.Type GetGeneratedType(CompilerResults results)
    {
        string typeName = SampleClassGenerator.TypeName;

        return results.CompiledAssembly.GetType(typeName);
    }
}

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Show:
© 2014 Microsoft