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

You can use the Reference Manager dialog box to add and manage references to components that you, Microsoft, or another company developed. If you're developing a Windows Store app, your project automatically references all of the Windows 8 SDK and the .NET Framework. If you’re developing another type of project, you must add these references to the project manually.

Adding and Removing a Reference

To Add a Reference in a C# or Visual Basic Project

1. On the menu bar, choose File, Open.

2. Navigate to your solution or project.

3. In Solution Explorer, open the shortcut menu for the project node, and then choose Add Reference.

4. Specify the references to add, and then choose the OK button.

To remove a reference, open its shortcut menu, and then choose Remove.

To Add a Reference in a C++ Project

1. On the menu bar, choose File, Open.

2. Navigate to your solution or project.

3. In Solution Explorer, open the shortcut menu for the project node, and then choose References.

4. In the Property Pages dialog box, choose the Add New Reference button.

5. In the Add Reference dialog box, specify the references to add, and then choose the OK button.

To remove a reference, open its shortcut menu, and then choose Remove.

Reference Manager opens and lists the available references by group. The project type determines which of the following groups appear:

• Assemblies, with the Framework and Extensions subgroups.

• Solution, with the Projects subgroup.

• Windows, with the Core and Extensions subgroups. You can explore the references in the Windows SDK or extension SDKs by using the Object Browser.

• Browse, with the Recent subgroup.

Assemblies tab

The Assemblies tab lists all .NET Framework assemblies that are available for referencing. The Assemblies tab doesn’t list any assemblies from the global assembly cache (GAC) because assemblies in the GAC are part of the run-time environment. If you deploy or copy an application that contains a reference to an assembly that’s registered in the GAC, the assembly won’t be deployed or copied with the application, regardless of the Copy Local setting. For more information, see Project References.

When you manually add a reference to any of the EnvDTE namespaces (EnvDTE, EnvDTE80, EnvDTE90, EnvDTE90a, or EnvDTE100), set the Embed Interop Types property of the reference to False in the Properties window. Setting this property to True can cause build issues because of certain EnvDTE properties that can’t be embedded.

All desktop projects contain an implicit reference to mscorlib. Visual Basic projects contain an implicit reference to Microsoft.VisualBasic. In Visual Studio 2012, all projects contain an implicit reference to System.Core, even if it’s removed from the list of references.

If a project type doesn’t support Assemblies, the tab won’t appear in the Reference Manager dialog box.

The Assemblies tab consists of two sub-tabs:

1. Framework lists all assemblies that constitute the targeted Framework.

   • Advertised assemblies are in the Full Framework and enumerated in the Framework list when your project targets a Profile of the targeted Framework. Advertised assemblies are grey to differentiate them from the assemblies that exist in the targeted Framework profile of the project. For example, if a project targets .NET Framework 4 Client, the Framework list shows advertised assemblies from .NET Framework 4. When a user adds an advertised assembly, the user is notified that, after the Reference Manager dialog box is closed, the project will be retargeted to the .NET Framework 4 and the advertised assembly will be added.

   • Projects for Windows Store apps contain references to all of the assemblies in the targeted .NET for Windows Store apps by default on project creation. In managed projects, a read-only node under the References folder in Solution Explorer indicates the reference to the entire Framework. Accordingly, the Framework tab won’t enumerate any of the assemblies from the Framework and instead display the following message: “All of the Framework assemblies are already referenced. Please use the Object Browser to explore the references in the Framework.” For desktop projects, the Framework tab enumerates assemblies from the targeted Framework, and the user must add the references that the application requires.

2. Extensions lists all assemblies that external vendors of components and controls have developed to extend the targeted Framework. Depending on the purpose of the user application, it might need these assemblies.

   • Extensions is populated by enumerating the assemblies that are registered in the following locations:

     32-bit machine:
     HKEY_CURRENT_USER\SOFTWARE\Microsoft\[Target Framework Identifier]\v[Target Framework Version]\AssemblyFoldersEx\[UserComponentName]\@default=[Disk location of assemblies]
     HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\[Target Framework Identifier]\v[Target Framework Version]\AssemblyFoldersEx\[UserComponentName]\@default=[Disk location of assemblies]
     64-bit machine:
     HKEY_CURRENT_USER\SOFTWARE\Wow6432Node\Microsoft\[Target Framework Identifier]\v[Target Framework Version]\AssemblyFoldersEx\[UserComponentName]\@default=[Disk location of assemblies]
     HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\[Target Framework Identifier]\v[Target Framework Version]\AssemblyFoldersEx\[UserComponentName]\@default=[Disk location of assemblies]
     And older versions of the [Target Framework Identifier]
     

     For example, if a project targets the .NET Framework 4 on a 32-bit machine, Extensions will enumerate assemblies that are registered under \Microsoft\.NETFramework\v4.0\AssemblyFoldersEx\, \Microsoft\.NETFramework\v3.5\AssemblyFoldersEx\, \Microsoft\.NETFramework\v3.0\AssemblyFoldersEx\, and \Microsoft\.NETFramework\v2.0\AssemblyFoldersEx\.

COM tab

The COM tab lists all COM components that are available for referencing. If you want to add a reference to a registered COM DLL that contains an internal manifest, unregister the DLL first. Otherwise, Visual Studio adds the assembly reference as an ActiveX Control instead of as a native DLL.

If a project type doesn’t support COM, the tab won’t appear in the Reference Manager dialog box.

Solution tab

The Solution tab lists all compatible projects within the current solution, in the Projects sub-tab.

A project can reference another project that targets a different version of the .NET Framework. For example, you could create a project that targets the .NET Framework 4 but that references an assembly that’s been built for the .NET Framework 2. However, the .NET Framework 2 project can’t reference a .NET Framework 4 project. For more information, see Targeting a Specific .NET Framework Version or Profile.

A project that targets the .NET Framework 4 is incompatible with a project that targets the .NET Framework 4 Client Profile.

In Visual Studio 2012, a file reference instead of a project reference is created if one project targets the .NET Framework 4 and another project targets an earlier version.

A project that targets the .NET for Windows Store apps can’t add a project reference to a project that targets the .NET Framework and vice versa.

Windows tab

The Windows tab lists all SDKs that are specific to platforms on which Windows operating systems run.

You can generate a WinMD file in Visual Studio in two ways:

• Windows Store app managed projects: Windows Store app projects can output WinMD binaries by setting Project Properties | Output Type = WinMD File. The WinMD filename must be the superset namespace of all the namespaces that exist within it. For example, if a project consists of namespaces A.B and A.B.C, the possible names for its outputted WinMD are A.winmd and A.B.winmd. If a user enters a Project Properties | Assembly Name or Project Properties | Namespace value that’s disjoint from the set of namespaces in the project or there is no superset namespace within a project, a build warning is generated: 'A.winmd' isn’t a valid .winmd file name for this assembly. All types within a Windows Metadata file must exist in a sub namespace of the file name. Types that don’t exist in a sub namespace of the file name won’t be able to be located at runtime. In this assembly, the smallest common namespace is 'CSWSClassLibrary1'. A desktop Visual Basic or Visual C# project can only consume WinMDs that are generated by using the Windows 8 SDKs, which are known as first-party WinMDs, and can’t generate WinMDs.

• Windows Store app native projects: A native WinMD file consists of only metadata. Its implementation exists in a separate DLL file. One can produce native binaries by choosing the Windows Runtime Component project template in the New Project dialog box or by starting from a blank project and modifying the project properties to generate a WinMD file. If the project consists of disjoint namespaces, a build error will tell the user to combine their namespaces or run the MSMerge tool.

The Windows tab consists of two subgroups.

Core Subgroup

The Core subgroup lists all of the WinMDs (for Windows Runtime elements) in the SDK for the targeted version of Windows.

Windows Store app projects contain references to all of the WinMDs in the Windows 8 SDK by default on project creation. In managed projects, a read-only node under the References folder in Solution Explorer indicates the reference to the entire Windows 8 SDK. Accordingly, the Core subgroup in the Reference Manager won’t enumerate any of the assemblies from the Windows 8 SDK and instead displays a message: “The Windows SDK is already referenced. Please use the Object Browser to explore the references in the Windows SDK.”

In the desktop projects, the Core subgroup doesn’t appear by default. You can add the Windows Runtime by opening the shortcut menu for the project node, choosing Unload Project, adding the following snippet, and re-opening the project (on the project node, choose Reload Project). When you invoke the Reference Manager dialog box, the Core subgroup appears.

  <PropertyGroup>
    <TargetPlatformVersion>8.0</TargetPlatformVersion>
  </PropertyGroup>

Make sure to select the Windows check box on this subgroup. You should then be able to use Windows Runtime elements. However, you'll also want to add System.Runtime, in which the Windows Runtime defines some standard classes and interfaces, such as IEnumerable, that are used throughout the Windows Runtime libraries. For information about how to add System.Runtime, see Managed desktop apps and Windows Runtime.

Extensions Subgroup

Extensions lists the user SDKs that extend the targeted Windows platform. This tab appears for Windows Store app projects only. Desktop projects won’t show this tab because they can consume only first-party .winmd files.

An SDK is a collection of files that Visual Studio treats as a single component. In the Extensions tab, SDKs that apply to the project from which the Reference Manager dialog box was invoked are listed as single entries. When added to a project, all of the SDK content is consumed by Visual Studio such that the user doesn’t need to take any further actions to leverage the SDK contents in IntelliSense, toolbox, designers, Object Browser, build, deployment, debugging, and packaging. For information about how to display your SDK in the Extensions tab, see Creating a Software Development Kit.

If a project type doesn’t support Extensions, the tab doesn’t appear in the Reference Manager dialog box.

Browse button

You can use the Browse button to browse for a component in the file system.

A project can reference a component that targets a different version of the .NET Framework. For example, you could create an application that targets the .NET Framework 4 Client Profile, which references a component that targets the .NET Framework 2. For more information, see Targeting a Specific .NET Framework Version or Profile.

You should avoid adding file references to outputs of another project in the same solution, because this tactic may cause compilation errors. Instead, use the Solution tab of the Reference Manager dialog box to create project-to-project references. This tactic makes team development easier by enabling better management of the class libraries that you create in your projects. For more information, see Troubleshooting Broken References.

You can’t browse to an SDK and add it to your project. You can only browse to a file (for example, an assembly or .winmd) and add it to your project.

When doing a file reference to a WinMD, the expected layout is that the FileName.winmd, FileName.dll, and FileName.pri files are all placed alongside each other. If you reference a WinMD in the following scenarios, an incomplete set of files will be copied into the project output directory and, consequently, build and runtime failures will occur.

• Native component: a native project will create one WinMD for each disjoint set of namespaces and one DLL that consists of the implementation. The WinMDs will have disparate names. When referencing this native component file, MSBuild won’t recognize that the dissimilarly named WinMDs make one component. Consequently, only the identically named FileName.dll and FileName.winmd will be copied, and runtime errors will occur. To work around this issue, create an Extension SDK. For more information, see Creating a Software Development Kit.

• Consuming controls: at a minimum, a XAML control consists of a FileName.winmd, FileName.dll, FileName.pri, XamlName.xaml, and an ImageName.jpg. When the project is built, the resource files that are associated with the file reference won’t get copied into the project’s output directory, and only FileName.winmd, FileName.dll and FileName.pri will be copied. A build error is logged to inform the user that the resources XamlName.xaml and ImageName.jpg are missing. To succeed, the user will have to manually copy these resource files into the project output directory for build and debugging/runtime. To work around this issue, either create an Extension SDK by following the steps in Creating a Software Development Kit or edit the project file to add the following property:

  <PropertyGroup>
  <GenerateLibraryOutput>True</GenerateLibraryOutput>
  </PropertyGroup>
  

  Note

  If you add the property, the build might run slower.

Recent

Assemblies, COM, Windows, and Browse each support a Recent tab, which enumerates the list of components that were recently added to projects.

Search

The search bar in the Reference Manager dialog box operates over the tab that’s in focus. For example, if a user types “System” in the search bar while the Solution tab is in focus, the search won’t return any results unless the solution consists of a project name that contains “System”.

See Also

Tasks

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

Concepts

Managing Project References