Building a WPF Application (WPF)

Windows Presentation Foundation (WPF) applications can be built as .NET Framework executables (.exe), libraries (.dll), or a combination of both types of assemblies. This topic introduces how to build WPF applications and describes the key steps in the build process.

This topic contains the following sections.

• Building a WPF Application
• WPF Build Pipeline
• Incremental Build Support
• Related Topics

Building a WPF Application

A WPF application can be compiled in the following ways:

• Command-line. The application must contain only code (no XAML) and an application definition file. For more information, see Command-line Building With csc.exe or Building from the Command Line (Visual Basic).

• Microsoft Build Engine (MSBuild). In addition to the code and XAML files, the application must contain an MSBuild project file. For more information, see MSBuild.

• Visual Studio. Visual Studio is an integrated development environment that compiles WPF applications with MSBuild and includes a visual designer for creating UI. For more information, see Application Development in Visual Studio and WPF Designer.

WPF Build Pipeline

When a WPF project is built, the combination of language-specific and WPF-specific targets are invoked. The process of executing these targets is called the build pipeline, and the key steps are illustrated by the following figure.

Pre-Build Initializations

Before building, MSBuild determines the location of important tools and libraries, including the following:

• The .NET Framework.

• The Windows SDK directories.

• The location of WPF reference assemblies.

• The property for the assembly search paths.

The first location where MSBuild searches for assemblies is the reference assembly directory (%ProgramFiles%\Reference Assemblies\Microsoft\Framework\v3.0\). During this step, the build process also initializes the various properties and item groups and performs any required cleanup work.

Resolving References

The build process locates and binds the assemblies required to build the application project. This logic is contained in the ResolveAssemblyReference task. All assemblies declared as Reference in the project file are provided to the task along with information on the search paths and metadata on assemblies already installed on the system. The task looks up assemblies and uses the installed assembly's metadata to filter out those core WPF assemblies that need not show up in the output manifests. This is done to avoid redundant information in the ClickOnce manifests. For example, since PresentationFramework.dll can be considered representative of an application built on and for the WPF and moreover since all WPF assemblies exist at the same location on every machine that has the .NET Framework installed, there is no need to include all information on all .NET Framework reference assemblies in the manifests.

Markup Compilation—Pass 1

In this step, XAML files are parsed and compiled so that the runtime does not spend time parsing XML and validating property values. The compiled XAML file is pre-tokenized so that, at run time, loading it should be much faster than loading a XAML file.

During this step, the following activities take place for every XAML file that is a Page build item:

1. The XAML file is parsed by the markup compiler.

2. A compiled representation is created for that XAML and copied to the obj\Release folder.

3. A CodeDOM representation of a new partial class is created and copied to the obj\Release folder.

In addition, a language-specific code file is generated for every XAML file. For example, for a Page1.xaml page in a Visual Basic project, a Page1.g.vb is generated; for a Page1.xaml page in a C# project, a Page1.g.cs is generated. The ".g" in the file name indicates the file is generated code that has a partial class declaration for the top-level element of the markup file (such as Page or Window). The class is declared with the partial modifier in C# (Extends in Visual Basic) to indicate there is another declaration for the class elsewhere, usually in the code-behind file Page1.xaml.cs.

The partial class extends from the appropriate base class (such as Page for a page) and implements the System.Windows.Markup.IComponentConnector interface. The IComponentConnector interface has methods to initialize a component and connect names and events on elements in its content. Consequently, the generated code file has a method implementation like the following:

public void InitializeComponent() {
    if (_contentLoaded) {
        return;
    }
    _contentLoaded = true;
    System.Uri resourceLocater = 
        new System.Uri(
            "window1.xaml", 
            System.UriKind.RelativeOrAbsolute);
    System.Windows.Application.LoadComponent(this, resourceLocater);
}

Public Sub InitializeComponent() _

    If _contentLoaded Then
        Return
    End If

    _contentLoaded = True
    Dim resourceLocater As System.Uri = _
        New System.Uri("mainwindow.xaml", System.UriKind.Relative)

    System.Windows.Application.LoadComponent(Me, resourceLocater)

End Sub

By default, markup compilation runs in the same AppDomain as the MSBuild engine. This provides significant performance gains. This behavior can be toggled with the AlwaysCompileMarkupFilesInSeparateDomain property. This has the advantage of unloading all reference assemblies by unloading the separate AppDomain.

Markup Compilation—Pass 2

Not all XAML pages are compiled at during pass 1 of markup compilation. XAML files that have locally defined type references (references to types defined in code elsewhere in the same project) are exempt from compilation at this time. This is because those locally defined types exist only in source and have not yet been compiled. In order to determine this, the parser uses heuristics that involve looking for items such as x:Name in the markup file. When such an instance is found, that markup file’s compilation is postponed until the code files have been compiled, after which, the second markup compilation pass processes these files.

File Classification

The build process puts output files into different resource groups based on which application assembly they will be placed in. In a typical nonlocalized application, all data files marked as Resource are placed in the main assembly (executable or library). When UICulture is set in the project, all compiled XAML files and those resources specifically marked as language-specific are placed in the satellite resource assembly. Furthermore, all language-neutral resources are placed in the main assembly. In this step of the build process, that determination is made.

The ApplicationDefinition, Page, and Resource build actions in the project file can be augmented with the Localizable metadata (acceptable values are true and false), which dictates whether the file is language-specific or language-neutral.

Core Compilation

The core compile step involves compilation of code files. This is orchestrated by logic in the language-specific targets files Microsoft.CSharp.targets and Microsoft.VisualBasic.targets. If heuristics have determined that a single pass of the markup compiler is sufficient, then the main assembly is generated. However, if one or more XAML files in the project have references to locally defined types, then a temporary .dll file is generated so the final application assemblies may be created after the second pass of markup compilation is complete.

Manifest Generation

At the end of the build process, after all the application assemblies and content files are ready, the ClickOnce manifests for the application are generated.

The deployment manifest file describes the deployment model: the current version, update behavior, and publisher identity along with digital signature. This manifest is intended to be authored by administrators who handle deployment. The file extension is .xbap (for XAML browser applications (XBAPs)) and .application for installed applications. The former is dictated by the HostInBrowser project property and as a result the manifest identifies the application as browser-hosted.

The application manifest (an .exe.manifest file) describes the application assemblies and dependent libraries and lists permissions required by the application. This file is intended to be authored by the application developer. In order to launch a ClickOnce application, a user opens the application's deployment manifest file.

These manifest files are always created for XBAPs. For installed applications, they are not created unless the GenerateManifests property is specified in the project file with value true.

XBAPs get two additional permissions over and above those permissions assigned to typical Internet zone applications: WebBrowserPermission and MediaPermission. The WPF build system declares those permissions in the application manifest.

Incremental Build Support

The WPF build system provides support for incremental builds. It is fairly intelligent about detecting changes made to markup or code, and it compiles only those artifacts affected by the change. The incremental build mechanism uses the following files:

• An $(AssemblyName)_MarkupCompiler.Cache file to maintain current compiler state.

• An $(AssemblyName)_MarkupCompiler.lref file to cache the XAML files with references to locally defined types.

The following is a set of rules governing incremental build:

• The file is the smallest unit at which the build system detects change. So, for a code file, the build system cannot tell if a type was changed or if code was added. The same holds for project files.

• The incremental build mechanism must be cognizant that a XAML page either defines a class or uses other classes.

• If Reference entries change, then recompile all pages.

• If a code file changes, recompile all pages with locally defined type references.

• If a XAML file changes:

  • If XAML is declared as Page in the project: if the XAML does not have locally defined type references, recompile that XAML plus all XAML pages with local references; if the XAML has local references, recompile all XAML pages with local references.

  • If XAML is declared as ApplicationDefinition in the project: recompile all XAML pages (reason: each XAML has reference to an Application type that may have changed).

• If the project file declares a code file as application definition instead of a XAML file:

  • Check if the ApplicationClassName value in the project file has changed (is there a new application type?). If so, recompile the entire application.

  • Otherwise, recompile all XAML pages with local references.

• If a project file changes: apply all preceding rules and see what needs to be recompiled. Changes to the following properties trigger a complete recompile: AssemblyName, IntermediateOutputPath, RootNamespace, and HostInBrowser.

The following recompile scenarios are possible:

• The entire application is recompiled.

• Only those XAML files that have locally defined type references are recompiled.

• Nothing is recompiled (if nothing in the project has changed).

See Also

Concepts

Deploying a WPF Application (WPF)

Pack URIs in WPF

WPF Application Resource, Content, and Data Files

Other Resources

WPF MSBuild Reference