Create Your Application as a Platform Builder Subproject (Compact 2013)

  • Article

10/26/2015

You can create an application project within an existing OS design project. An application project created by using this workflow is called a Platform Builder subproject. This workflow assumes that you will download the run-time image to the target device or to a virtual device by using Platform Builder and then run your application from Microsoft Visual Studio 2013 or Microsoft Visual Studio 2015 each time you want to test a change.

Tip

If you do not have Platform Builder, and you plan to test your application on a stand-alone virtual device that includes the run-time image on a virtual drive or on a device that has the run-time image in flash memory, use the procedure in Create Your Application Using an SDK for an OS Image instead.

Prerequisites

To complete the following procedure, you must:

  • Include Platform Builder when you install Windows Embedded Compact 2013. Platform Builder is an add-in to the Visual Studio integrated development environment. For more information, see Install Windows Embedded Compact 2013.
  • Create an OS design project or have access to one. For more information, see Create Your First OS.
  • Have access to the virtual device or device for which the OS was designed. With a virtual device, you will be able to test most of your application on your computer instead of on the device, until you are further along in the development cycle when it becomes more important to test directly on the device. For information about creating a virtual device, see Use the Sample Virtual Device.

To create an application subproject in the OS design project

  1. In Visual Studio, open the project for the OS design.

  2. Optional. You can review the features of Windows Embedded Compact that have been included in the OS design to ensure that the ones you want to use in your application are selected. To view the catalog, click View > Other Windows > Catalog Items View. For example, your application will be able to respond to mouse clicks if the Mouse catalog item is selected in the User Interface node.

    Tip

    For information about how to add catalog items to the OS design, see Create Your First OS. To determine which catalog items to add for a feature, see the reference topic "Catalog Items and Sysgen Variables" for the feature that you want to include. For example, to add common UI elements to your OS design, see the topic Common Controls Catalog Items and Sysgen Variables in the Reference section of the Help documentation. If someone on your team is responsible for designing the OS, you might want to let them know that you need a specific catalog item added to the OS design.

  3. If you have not already done so, or if you have changed the OS design project by modifying catalog items or configuration properties, save all your project files and build the OS design to create a run-time image in preparation for downloading the run-time image to the device or virtual device. On the Build menu, click Build Solution. After the build completes, click Make Run-Time Image on the Build menu.

    Tip

    You can configure Visual Studio to create a new run-time image each time you build your OS design project. On the Build menu, point to Targeted Build Settings, and then select Make Run-Time Image After Building.

  4. Optional. If you are converting a Blend for Visual Studio project into a XAML for Windows Embedded project, first create a Windows Embedded Compact-compatible project template from the Expression Blend project. To create a compatible project template, on the Tools menu, point to **Windows Embedded XAML Tools **, and then click Create Platform Builder Subproject.

    Complete the steps of the Create Platform Builder Subproject wizard and make a note of the location where your converted project is saved. For detailed information, see Convert an Expression Blend Project to a XAML for Windows Embedded Application Template.

  5. In Solution Explorer, expand the OS design project node, and then right-click Subprojects, and do one of the following:

    • Click Add New Subproject if you want to create a new subproject for an application that will run on your OS, and complete the following steps.

      1. In the Subproject Wizard that appears, on the Select name, location and template page, select an application template, enter a subproject name, and provide a location to save the auto-generated subproject files to.

      2. Click Next.

      3. On the Auto-generated subproject files page, select how much code you want generated for you.

        Tip

        Do not select the Empty project option unless you want to start out without any source files.

      4. Click Finish.

    • Click Add Existing Subproject if you already have an application project that you want to add to your OS design or if you have a project template that was converted from an Expression Blend project. Then complete the following steps.
      1. In the Open dialog box, select the project file (such as a VCPROJ file, an SLN file, or a PBPXML file) for the project that you want to add.
      2. Click Open.

    The subproject that you add, either as a new or existing project, appears in Solution Explorer under Subprojects.

  6. If you plan to debug your application, do the following:

    1. Configure your OS design to build the debug version of the OS. Click Configuration Manager on the Build menu, then set the Active solution configuration to the Debug configuration.
    2. Configure your OS design to Enable KITL. Open the Property Pages for the OS design project (not the solution), expand Configuration Properties, select Build Options, and then change Enable Kernel Independent Transport Layer (KITL) to Yes.
    3. Configure your application subproject to be excluded from the run-time image and to always debug. In the Property Pages for the OS design project, expand Configuration Properties, select Subproject Image Settings, and then edit the properties for each project.

    Warning

    By default, an application subproject is configured to be included in the run-time image, but it is not a part of the run-time image until the next time you rebuild your OS design and run-time image. If an application is included in the run-time image, every change that you make to your application will require you to rebuild the OS design project and run-time image before downloading the image and testing your application. If you want to download the run-time image only once and keep a live connection to it from Visual Studio, then you can exclude your subproject from the run-time image and just rebuild and restart your application when you want to test a change.

  7. To build only the application (and not the entire OS design project), right-click your subproject name and click Build.

Next Steps

You can now develop your application by adding code to the source file, creating new source files, and so on.

To test your application, you must use the device or virtual device for which the OS was designed. Make a connection to your device or virtual device, download the run-time image, and then on the Target menu in Visual Studio, click Run Programs to start your application.

Important

The device or virtual device on which you test your application must not contain a stand-alone run-time image. You don't need a stand-alone run-time image because you have the OS design project open in Visual Studio, which you can use to download the run-time image to the device or virtual device before testing your application. Also, you will not be able to test your application on a stand-alone virtual device if you're starting the application from within an OS design project.

For information about how to create a virtual device and download an OS, see Set Up a Virtual Test Device and Download the OS to the Device. For more information about how to create a stand-alone virtual device, see Create a Virtual Device for Use with an SDK.

See Also

Concepts

Create a Project for a Windows Embedded Compact Application