Moving existing Flex projects from Flex Builder 3 to Flash Builder 4

If you want to start using Flash Builder 4 with your existing Flex 3 projects, there are a number of different approaches you can take, depending on the Flex SDK features you want to use and the amount of migration work you're prepared to undertake.

Below is a quick guide to the options available to you, ordered by the amount of migration effort potentially required―from no effort (for using the existing Flex 3 SDK in Flash Builder 4) up to a full migration using all the new Flex 4 SDK language features and Spark components.

Note: To learn about the differences between Flex 3 SDK and Flex 4 SDK, you should read the article Differences between Flex 3 and Flex 4.

I want the new Flash Builder 4 features, but can't switch SDK versions.

Migration required: None; requires Flash Player 9 or higher

You can move existing Flex 3 applications, developed using Flex Builder 3, to Flash Builder 4 without needing to migrate the application to use the Flex 4 SDK―this enables you to get the benefit of most new Flash Builder 4 features straight away on an existing project.

Flash Builder 4 features include a network monitor, enhanced debugging, new refactoring support, code editing improvements, unit testing support, and the data-centric development (DCD) workflow―in total more than 50 features that will make you more productive when building Flex applications.

Watch James Ward demonstrate some of the new features in Flash Builder 4 that work with a project based on the Flex 3 SDK.

Follow the steps below to import projects into Flash Builder 4 and continue using Flex 3 SDK:

1. In Flash Builder 4, go to File > Import > Flash Builder Project… (see Figure 1).

2. After importing the project, you will see a dialog box asking you to choose the Flex SDK version of the project. Flash Builder 4 comes pre-installed with the latest version of the Flex 3 SDK, version 3.5.

   If your project is already based on Flex SDK 3.5 or you would like to move it to the latest release, then select Flex 3.5 from the "Use a specific SDK" pull-down menu (see Figure 2) and skip to Step 5.

If you were using Flex SDK 3.4 or earlier, then you will need to download the required SDK and configure Flash Builder 4 to use it―this is straightforward and only needs to be done once.

From the Adobe Open Source website, select a Milestone Release Build for Flex SDK 3.0, 3.1, 3.2, 3.3 or 3.4, depending on the SDK you are using with your project (you can check this in Flex Builder 3 by looking at the 'Flex Compiler' properties for the project). Alternatively select a stable or nightly build if you know that is what you need.

Unzip the downloaded SDK into the sdks folder in the Flash Builder 4 application folder ―on Mac OS X this will likely be /Applications/Adobe Flash Builder 4/sdks/ and on Windows /Program Files/Adobe/Adobe Flash Builder 4/sdks.

3. Click the "Configure Flex SDKs…" link, the Choose Flex SDK Version dialog box, and then the "Add…" button. Select the SDK folder you just unzipped and Flash Builder should recognize it and add it to the list of installed Flex SDKs (see Figure 3).

Make sure to then select the newly installed SDK as the version in the "Use a specific SDK" pull-down menu.

4. In the "Project will be upgraded" dialog box, select OK to make the project compatible with Flash Builder 4 (note that this will mean the project can no longer be opened in Flex Builder 3, but all your MXML and ActionScript files are still accessible via the file system should you want to merge any changes back into your project in Flex Builder 3) (see Figure 4).

5. After completing the import process you may see an error reported in the Problems view that relates to the creation of the HTML Wrapper (see Figure 5). To resolve this issue, simply right click on the message and select "Recreate HTML Templates".

You are now ready to continue working on your Flex 3 project in Flash Builder 4!

I want the new Flash Builder 4 features and the faster Flex 4 compiler, but I need to maintain my application's existing behavior.

Migration required: Code changes unlikely; requires Flash Player 10

To use the faster Flex 4 compiler with an existing Flex 3 project, you can import it into Flash Builder 4 and use the "Flex 3 compatibility mode" option (see Figure 6)―this maintains the existing behavior of the application and shouldn't require any changes to your code. You should however see significantly improved compile times for the project.

Note however that none of the Flex 4 language features or the new Spark components will be available in the project.

Choosing this checkbox sets the –compatibility-version flag on the compiler to 3.0. For more information on what this flag does, refer to this document.

I want the new Flash Builder 4 features and all the new Flex 4 language features, but I don't want to adopt the new Spark component architecture.

Migration required: Some code changes likely as Flex 4 features are incorporated; Flash Player 10 required

To make use of just the new Flex 4 language features in your existing project you can choose to use the Flex 4 SDK during the project import, but then specify that only the MX component set is available. You can do this by going Project > Properties > Flex Build Path and selecting "MX only" component set from the Library Path dialog box once you've imported the project (see Figure 7).

The new language features available to you include two-way data binding, the new States model, declarative layouts, enhanced effects, and advanced CSS.

You will notice the following behaviors in Flash Builder:

• New documents will use the MXML 2009 namespace
• The components panel in design view will show only MX components
• Content assist will show only MX components
• Halo theme will be set by default
• Flex 4 language features are only available in documents using the MXML 2009 namespace
• Advanced CSS is supported, however existing CSS Type selectors will need to have namespaces added (you will see compiler warnings otherwise and styles will not be applied correctly).

For more information on these features, and potential issues you may encounter whilst migrating your application, review the Flex 4 features and migration guide.

I want the new Flash Builder 4 features, all the new Flex 4 language features and I want to add Spark-based components into my existing application.

Migration required: Some code changes likely as Flex 4 features are incorporated; Flash Player 10 required

You can continue to use existing MX components alongside the newer Spark components in the same Flex application, allowing for a gradual adoption of the new component architecture. You should only replace existing MX components with Spark components if required; instead focus on using Spark components when adding new functionality to your application.

Upon importing your Flex 3 project into Flash Builder 4 and selecting to use the Flex 4 SDK, you will notice the following behaviors in Flash Builder:

• New documents will use the MXML 2009 namespace
• Content assist will list Spark components before MX components
• The components panel in design view will show Spark components in documents with the MXML 2009 namespace and MX components in documents with the MXML 2006 namespace
• Spark theme will be set by default
• Flex 4 language features are available in documents using the MXML 2009 namespace
• Advanced CSS is supported, however existing CSS Type selectors will need to have namespaces added (you will see compiler warnings otherwise and styles will not be applied correctly).

For more information on these features, and potential issues you may encounter while migrating your application, review the Flex 4 features and migration guide.

To learn more about what's new in Flash Builder 4, you should take a look at the following resources:

• Five most-asked for features from developers
• Developer productivity enhancements
• A complete list of new features in Flash Builder 4
• Flash Builder 4 secrets (great tips on how to be more productive)
• Data-centric development