Managing Project References

Before you write code against an external component, your project must first contain a reference to that component. You can make a reference to the following types of components:

• Windows Store app references

• .NET Framework class libraries or assemblies

• COM components

• Other assemblies or class libraries of projects in the same solution

• XML Web services

For more information about XML Web service references, see Web References.

Windows Store App References

Project References

Windows Store projects that target Windows 8 cannot depend upon Windows Store projects or binaries that target Windows 8.1.

If any project in your app targets Windows 8.1 and your app consists of a C++ Windows Store project, you will need to perform the following steps:

1. Retarget all the projects in your app to Windows 8.1. Right-click on each project in your app and select the Retarget to Windows 8.1 command, then click OK on the Review Project and Solution Changes dialog.

2. Right-click on every Visual Basic, Visual C#, and JavaScript project that depends on a C++ Windows Store project, choose Add Reference, go to the Windows tab, then the Extensions sub-tab, uncheck Microsoft Visual C++ Runtime Package v11.0 and check Microsoft Visual C++ Runtime Package v12.0, then click OK.

Visual Basic, C# and JavaScript Windows Store projects that target Windows 8.1 can reference Visual Basic and C# Windows Store projects that target Windows 8, provided that these projects do not use APIs that have been deprecated in Windows 8.1. See Migrating Windows 8 apps to Windows 8.1 Preview to find out whether Windows Store projects that target Windows 8 will continue to behave as expected when referenced from a Windows 8.1 project.

Extension SDK References

Visual Basic, C#, C++ and JavaScript Windows Store projects that target Windows 8.1 cannot reference Extension SDKs that depend on Microsoft Visual C++ Runtime Package v11.0, because this will cause runtime issues. You can find out whether an Extension SDK depends on Microsoft Visual C++ Runtime Package v11.0 by creating a new C# Windows Store project, right-clicking on the project and choosing Add Reference, going to the Windows tab, then the Extensions sub-tab, selecting the Extension SDK and seeing if the right pane in the Reference Manager lists Microsoft.VCLibs, version = 11.0 as a dependency.

Visual Basic, C# and JavaScript Windows Store projects that target Windows 8.1 can reference Extension SDKs that do not depend on the Microsoft Visual C++ Runtime Package v11.0, as long as that these Extension SDKs do not use APIs that have been deprecated in Windows 8.1. Please check the Extension SDK vendor site to find out whether it can be referenced by Windows Store projects that target Windows 8.1.

If you determine that the Extension SDK being referenced by your app is not supported, then you need to perform the following steps:

1. Look at the name of the project that is causing the error. The platform your project is targeting is noted in parentheses next to the project name. For example, MyProjectName (Windows 8.1) means that your project MyProjectName is targeting platform version Windows 8.1.

2. Go to the site of the vendor who owns the unsupported Extension SDK and install the version of the Extension SDK with dependencies that are compatible with the version of the platform your project is targeting.

   Note

   One way to find out whether an Extension SDK has dependencies on other Extension SDKs is to restart Visual Studio, create a new C# Windows Store project, right-click on the project and choose Add Reference, go to the Windows tab, go to the Extensions sub-tab, select the Extension SDK and look at the right pane in the Reference Manager. If it has dependencies, they will be listed there.

   Important

   If your project is targeting Windows 8.1, and the Extension SDK installed in the previous step has a dependency on the Microsoft Visual C++ Runtime Package, the version of Microsoft Visual C++ Runtime Package that is compatible with Windows 8.1 is v12.0 and is installed with Visual Studio 2013.

3. If the Extension SDK you installed in the previous step has dependencies on other Extension SDKs, go to the site(s) of the vendor(s) who own the dependencies and install the versions of these dependencies that are compatible with the version of the platform your project is targeting.

4. Restart Visual Studio and open your app.

5. Right-click on the project that caused the error and choose Add Reference (in Visual Basic, C#, or JavaScript projects) or References (in C++ projects). For C++ projects, click on the Add New Reference button.

6. Click the Windows tab and then the Extensions sub-tab, then uncheck the checkboxes for the old Extension SDKs and check the checkboxes for the new Extension SDKs. Click OK.

Adding a Reference at Design Time

To add one or more references at design time, you use either the Reference Manager dialog box or the Add Reference dialog box, depending on which type of project you're building. You use the Reference Manager dialog box for all Windows Store apps and most other types of projects. For more information, see How to: Add or Remove References By Using the Reference Manager. A few other project types support the Add Reference dialog box. For more information, see How to: Add or Remove References By Using the Add Reference Dialog Box.

You can use the Add Reference dialog box to browse to assemblies that aren't listed. You can't add references from the Global Assembly Cache (GAC), as it's strictly part of the run-time environment.

When you make a reference to an assembly in your project, Visual Studio searches for the assembly in the following locations:

• The current project directory. (You can find these assemblies by using the Browse tab.)

• Other project directories in the same solution. (You can find these assemblies on the Projects tab.)

For more information about how to add references at design time, see How to: Add or Remove References By Using the Add Reference Dialog Box.

References to Shared Components at Run Time

At run time, components must be either in the output path of the project or in the Global Assembly Cache (GAC). If the project contains a reference to an object that is not in one of these locations, you must copy the reference to the output path of the project when you build the project. The CopyLocal property indicates whether this copy has to be made. If the value is True, the reference is copied to the project directory when you build the project. If the value is False, the reference is not copied.

If you deploy an application that contains a reference to a custom component that is registered in the GAC, the component will not be deployed with the application, regardless of the CopyLocal setting. In earlier versions of Visual Studio, you could set the CopyLocal property on a reference to ensure that the assembly was deployed. Now, you must manually add the assembly to the \Bin folder. This puts all custom code under scrutiny, reducing the risk of publishing custom code with which you are not familiar.

By default, the CopyLocal property is set to False if the assembly or component is in the global assembly cache or is a framework component. Otherwise, the value is set to True. Project-to-project references are always set to True.

Referencing a Project or Assembly That Targets a Different Version of the .NET Framework

You can create applications that reference projects or assemblies that target a different version of the .NET Framework. For example, you could create an application that targets the .NET Framework 4 Client Profile that references an assembly that targets .NET Framework 2.0. If you create a project that targets an earlier version of the .NET Framework, you cannot set a reference in that project to a project or assembly that targets the .NET Framework 4 Client Profile or .NET Framework version 4. 

For more information, see Targeting a Specific .NET Framework Version or Profile.

Project-to-Project References and File References

File references are direct references to assemblies; you create them by using the Browse tab of the Add Reference dialog box. Project-to-project references are references to projects that contain assemblies; you create them by using the Project tab of the Add Reference dialog box.

The advantage of a project-to-project reference is that it creates a dependency between the projects in the build system. Therefore, the dependent project will be built if it has changed since the last time the referencing project was built. A file reference does not create a build dependency, so it is possible to build the referencing project without building the dependent project, and the reference can become obsolete. (That is, the project can reference a previously built version of the project.) This can result in several versions of a single DLL being required in the bin directory, which is not possible. When this conflict occurs, you will see a message such as Warning: the dependency 'file' in project 'project' cannot be copied to the run directory because it would overwrite the reference 'file.'.

You should avoid adding file references to outputs of another project in the same solution, because doing this may cause compilation errors. Instead, use the Projects tab of the Add Reference dialog box to create project-to-project references within the same solution. This makes team development easier by allowing for better management of the class libraries you create in your projects. For more information, see Troubleshooting Broken References and How to: Create and Remove Project Dependencies.

Web References

You can also add Web references by using the Add Web Reference dialog box. For more information, see How to: Add and Remove Web References.

See Also

Tasks

Troubleshooting Broken References

How to: Add or Remove References By Using the Add Reference Dialog Box

Concepts

How to: Add or Remove References By Using the Reference Manager

Other Resources

Referencing Namespaces and Components

Managing References

Programming with Assemblies