doc/netfx.xsd

<?xml version="1.0" encoding="utf-8"?>
<!--
  <copyright file="netfx.xsd" company="Outercurve Foundation">
    Copyright (c) 2004, Outercurve Foundation.
    This software is released under Microsoft Reciprocal License (MS-RL).
    The license and further copyright text can be found in the file
    LICENSE.TXT at the root directory of the distribution.
  </copyright>
-->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
          xmlns:xse="http://schemas.microsoft.com/wix/2005/XmlSchemaExtension"
         xmlns:html="http://www.w3.org/1999/xhtml"
    targetNamespace="http://schemas.microsoft.com/wix/NetFxExtension"
              xmlns="http://schemas.microsoft.com/wix/NetFxExtension">
    <xs:annotation>
        <xs:documentation>
            The source code schema for the Windows Installer XML Toolset .NET Framework Extension.
        </xs:documentation>
    </xs:annotation>

    <xs:element name="NativeImage">
        <xs:annotation>
            <xs:documentation>
                Improves the performance of managed applications by creating native images.
                Requires the .NET Framework 2.0 or newer to be installed on the target machine since
                it runs <html:a href="http://msdn2.microsoft.com/en-us/library/6t9t5wcf.aspx">NGen</html:a>.
            </xs:documentation>
            <xs:appinfo>
                <xse:parent namespace="http://schemas.microsoft.com/wix/2006/wi" ref="File" />
                <xse:remarks>
                    <html:p>
                        Native images are files containing compiled processor-specific machine code, which
                        are installed into the native image cache on the local computer. The runtime
                        can use native images from the cache instead using the just-in-time (JIT)
                        compiler to compile the original assembly.
                    </html:p>
                    <html:p>
                        The native image custom actions are configured to ignore failures so that failing
                        to generate or remove a native image will not cause setup to fail and roll back.
                    </html:p>
                    <html:p>
                        <html:b>Note for patches:</html:b> if you built your target, or baseline, MSI with
                        previous versions 3.0 or 3.5 of this extension and want to upgrade to formattable
                        values for @AssemblyApplication or @AppBaseDirectory you must also include a
                        BinaryRef to "NetFxCA" to pull in necessary changes. If you do use formattable
                        values and do not include the binary changes ngen.exe will not optimize your
                        native images for the specified application.
                    </html:p>
                    <html:p>
                        This should be a rare occurrence, however. Because you cannot remove components
                        in a patch - and pyro does validate you do not - it is not practical to switch
                        from using identifiers to formattable values in a patch. One practical possibility
                        is if you wanted to use a different application to optimize your native images
                        and that application is not already installed with the MSI to be updated.
                    </html:p>
                </xse:remarks>
            </xs:appinfo>
        </xs:annotation>
        <xs:complexType>
            <xs:attribute name="Id" type="xs:string" use="required">
                <xs:annotation>
                    <xs:documentation>
                        The identifier for this NativeImage.
                    </xs:documentation>
                </xs:annotation>
            </xs:attribute>
            <xs:attribute name="AppBaseDirectory" type="xs:string">
                <xs:annotation>
                    <xs:documentation>
                        <html:p>
                            The directory to use for locating dependent assemblies.
                            For DLL assemblies and assemblies installed to the Global Assembly Cache (GAC),
                            this attribute should be set to the directory of the application which loads this
                            assembly.  For EXE assemblies, this attribute does not need to be set because NGen
                            will use the directory of the assembly file by default.
                        </html:p>
                        <html:p>
                            The value can be in the form of a directory identifier, or a formatted string
                            that resolves to either a directory identifier or a full path to a directory.
                        </html:p>
                    </xs:documentation>
                </xs:annotation>
            </xs:attribute>
            <xs:attribute name="AssemblyApplication" type="xs:string">
                <xs:annotation>
                    <xs:documentation>
                        <html:p>
                            The application which will load this assembly.
                            For DLL assemblies which are loaded via reflection, this attribute should
                            be set to indicate the application which will load this assembly.
                            The configuration of the application (usually specified via an exe.config file) will be used
                            to determine how to resolve dependencies for this assembly.
                        </html:p>
                        <html:p>
                            The value can be in the form of a file identifier, or a formatted string
                            that resolves to either a file identifier or a full path to a file.
                        </html:p>
                        <html:p>
                            When a shared component is loaded at run time, using the Load method, the
                            application's configuration file determines the dependencies that are loaded
                            for the shared component — for example, the version of a dependency that is loaded.
                            This attribute gives guidance on which dependencies would be loaded at run time in order
                            to figure out which dependency assemblies will also need to have native images generated
                            (assuming the Dependency attribute is not set to "no").
                        </html:p>
                        <html:p>
                            This attribute cannot be set if the AssemblyApplication attribute is set on the parent
                            File element (please note that these attributes both refer to the same application
                            assembly but do very different things: specifiying File/@AssemblyApplication will force
                            an assembly to install to a private location next to the indicated application, whereas
                            this AssemblyApplication attribute will be used to help resolve dependent assemblies
                            while generating native images for this assembly).
                        </html:p>
                    </xs:documentation>
                </xs:annotation>
            </xs:attribute>
            <xs:attribute name="Debug" type="YesNoType">
                <xs:annotation>
                    <xs:documentation>
                        Set to "yes" to generate native images that can be used under a debugger.
                        The default value is "no".
                    </xs:documentation>
                </xs:annotation>
            </xs:attribute>
            <xs:attribute name="Dependencies" type="YesNoType">
                <xs:annotation>
                    <xs:documentation>
                        Set to "no" to generate the minimum number of native images.
                        The default value is "yes".
                    </xs:documentation>
                </xs:annotation>
            </xs:attribute>
            <xs:attribute name="Platform">
                <xs:annotation>
                    <xs:documentation>
                        Sets the platform(s) for which native images will be generated.
                    </xs:documentation>
                </xs:annotation>
                <xs:simpleType>
                    <xs:restriction base="xs:NMTOKEN">
                        <xs:enumeration value="32bit">
                            <xs:annotation>
                                <xs:documentation>
                                    Attempt to generate native images only for the 32-bit version of the .NET Framework
                                    on the target machine.  If the 32-bit version of the .NET Framework 2.0 or newer is not
                                    present on the target machine, native image custom actions will not be scheduled.
                                    This is the default value.
                                </xs:documentation>
                            </xs:annotation>
                        </xs:enumeration>
                        <xs:enumeration value="64bit">
                            <xs:annotation>
                                <xs:documentation>
                                    Attempt to generate native images only for the 64-bit version of the .NET Framework
                                    on the target machine.  If a 64-bit version of the .NET Framework 2.0 or newer is not
                                    present on the target machine, native image custom actions will not be scheduled.
                                </xs:documentation>
                            </xs:annotation>
                        </xs:enumeration>
                        <xs:enumeration value="all">
                            <xs:annotation>
                                <xs:documentation>
                                    Attempt to generate native images for the 32-bit and 64-bit versions of the .NET Framework
                                    on the target machine.  If a version of the .NET Framework 2.0 or newer is not present on the
                                    target machine for a processor architecture, native image custom actions will not be
                                    scheduled for that processor architecture.
                                </xs:documentation>
                            </xs:annotation>
                        </xs:enumeration>
                    </xs:restriction>
                </xs:simpleType>
            </xs:attribute>
            <xs:attribute name="Priority">
                <xs:annotation>
                    <xs:documentation>
                        Sets the priority of generating the native images for this assembly.
                    </xs:documentation>
                </xs:annotation>
                <xs:simpleType>
                    <xs:restriction base="xs:NMTOKEN">
                        <xs:enumeration value="0">
                            <xs:annotation>
                                <xs:documentation>
                                    This is the highest priority, it means that image generation occurs syncronously
                                    during the setup process.  This option will slow down setup performance.
                                </xs:documentation>
                            </xs:annotation>
                        </xs:enumeration>
                        <xs:enumeration value="1">
                            <xs:annotation>
                                <xs:documentation>
                                    This will queue image generation to the NGen service to occur immediately.
                                    This option will slow down setup performance.
                                </xs:documentation>
                            </xs:annotation>
                        </xs:enumeration>
                        <xs:enumeration value="2">
                            <xs:annotation>
                                <xs:documentation>
                                    This will queue image generation to the NGen service to occur after all priority 1
                                    assemblies have completed.
                                    This option will slow down setup performance.
                                </xs:documentation>
                            </xs:annotation>
                        </xs:enumeration>
                        <xs:enumeration value="3">
                            <xs:annotation>
                                <xs:documentation>
                                    This is the lowest priority, it will queue image generation to occur when the
                                    machine is idle.
                                    This option should not slow down setup performance.
                                    This is the default value.
                                </xs:documentation>
                            </xs:annotation>
                        </xs:enumeration>
                    </xs:restriction>
                </xs:simpleType>
            </xs:attribute>
            <xs:attribute name="Profile" type="YesNoType">
                <xs:annotation>
                    <xs:documentation>
                        Set to "yes" to generate native images that can be used under a profiler.
                        The default value is "no".
                    </xs:documentation>
                </xs:annotation>
            </xs:attribute>
        </xs:complexType>
    </xs:element>

    <xs:simpleType name="YesNoType">
        <xs:annotation>
            <xs:documentation>Values of this type will either be "yes" or "no".</xs:documentation>
        </xs:annotation>
        <xs:restriction base='xs:NMTOKEN'>
            <xs:enumeration value="no"/>
            <xs:enumeration value="yes"/>
        </xs:restriction>
    </xs:simpleType>

</xs:schema>