Project References

...

How EBuild resolves Project References

EBuild applies sophisticated logic to try its very bets to resolve project references in almost every case.

Firstly, before starting the build, EBuild will check all projects in the current solution for project references. Each project reference is matched against the other projects in the solution, and if a matching project is found, it is connected to the project reference, and marked to be built before the project(s) that reference it.

If a referenced project cannot be found in the solution, EBuild will try to locate the project file on disk using either its name or its ProjectFile meta data value. If found, the project is loaded into the solution implicitly and connected to the project reference, but marked as not Enabled (i.e. it will not be built).

If the referenced project cannot be found either, EBuild checks if the Hintpath of the reference is valid.

If none of these steps are successful, the build will fail.

EBuild will then determine the best build order for all projects, based on the dependencies. If a circular dependency is detected, the build will fail, otherwise EBuild will start to build each project in the order it has decided.

As each project hits the ElementsResolveReferences task, project references are resolved using the following steps:

If a live project was connected to the project reference

If a live project was connected to the project reference in the previous steps (either because it was part of the solution, or could be located on disk), that project is used to fill the reference:

  • If the project was built successfully, its output (via the FinlOutoutForReferencing-| collection) will be used to fulfill the reference.
  • If the referenced project is Enabled but was not built yet, that means a circular dependency was detected, and the referencing project will fail to build.
  • If the referenced project failed to built earlier, the referencing project will also fail to build.
  • If the project is not Enabled (either explicitly by the user, or because it was pulled into the solution implicitly as described above), EBuild will try to locate the project's FinalOutput.xml file in the Cache from a previous build. If found, the data from that file (the FinlOutoutForReferencing-| collection) will be used to fulfill the reference.
  • If the previous step failed, EBuild will fall back to using the HintPath, if valid, to fulfill the reference, and otherwise fail the build.

If no live project was connected

Otherwise, EBuild will fall back to simply looking at the HintPath. If valid, it will be used to fulfill the project reference, otherwise the build will fail.

Covered Scenarios

The steps above cover just about any valid scenario for project References:

  1. Both projects are in the solution and Enabled.
  2. Both projects are in the solution, the referenced project is not Enabled, but was built earlier.
  3. The referenced project is not in the solution, but can be located on disk and was built earlier.
  4. The referenced project cannot be located, but the HintPath is valid.

Project References when Hosting EBuild in MSBuild

When building with EBuild inside Visual Studio, EBuild does not see the whole solution, but instead builds each project individually (wrapped in an MSBuild project task). EBuild will rely on option 3 and 4 from above to resolve project references in that case.

The same is true when building an individual project file without .sln from the command line.