Integración de Visual Studio (MSBuild)

Actualización: noviembre 2007

Visual Studio 2005 aloja MSBuild para cargar y generar proyectos administrados. Puesto que MSBuild es responsable del proyecto, prácticamente cualquier proyecto con el formato de MSBuild puede utilizarse correctamente en Visual Studio, aunque el proyecto lo creara una herramienta diferente y tenga un proceso de generación personalizado.

En este tema se describen los aspectos específicos del alojamiento de MSBuild en Visual Studio que deben tenerse en cuenta al personalizar los proyectos y archivos .targets que se carguen y se generen en Visual Studio. Le ayudarán a garantizar que las funciones de Visual Studio como IntelliSense y la depuración funcionan para el proyecto personalizado.

Extensiones de nombre de archivo de los proyectos

MSBuild.exe reconoce cualquier extensión de nombre de archivo de proyecto que coincida con el modelo .*proj. Sin embargo, Visual Studio sólo reconoce un subconjunto de estas extensiones de nombre de archivo de proyecto, que determinan el sistema de proyectos específico del lenguaje que cargará el proyecto. Visual Studio no dispone de ningún sistema de proyectos independiente del lenguaje basado en MSBuild.

Por ejemplo, el sistema de proyectos de Visual C# carga archivos .csproj, pero Visual Studio no puede cargar ningún archivo .xxproj. Un archivo de proyecto para archivos de código fuente en un lenguaje arbitrario debe utilizar la misma extensión que los archivos de proyecto de Visual Basic, Visual C# o Visual J# que se van a cargar en Visual Studio.

Nombres de destino conocidos

Al hacer clic en el comando Generar en Visual Studio, se ejecutará el destino predeterminado del proyecto. A menudo, este destino también se denomina Build. Al elegir el comando Volver a generar o Limpiar, se intentará ejecutar un destino del mismo nombre en el proyecto. Al hacer clic en Publicar, se ejecutará un destino denominado PublishOnly en el proyecto.

Configuraciones y plataformas

Las configuraciones se representan en los proyectos de MSBuild mediante propiedades agrupadas en un elemento PropertyGroup que contiene un atributo Condition. Visual Studio examina estas condiciones para crear una lista de las configuraciones y plataformas del proyecto que se va a mostrar. Para extraer correctamente esta lista, las condiciones deben tener un formato similar al siguiente:

Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' "
Condition=" '$(Configuration)' == 'Release' " 
Condition=" '$(Something)|$(Configuration)|$(SomethingElse)' == 'xxx|Debug|yyy' "

Con este fin, Visual Studio examina las condiciones en PropertyGroup, ItemGroup, Import, en la propiedad y en los elementos.

Acciones de generación adicionales

Visual Studio permite cambiar el nombre de la colección de elementos de un archivo en un proyecto con la propiedad Acción de generación de la ventana Propiedades de archivo. Los nombres de la colección de elementos Compile, EmbeddedResource, Content y None siempre se muestran en este menú, junto con otros nombres de la colección de elementos presentes en el proyecto. Para garantizar que los nombres de la colección de elementos personalizada siempre estén disponibles en este menú, puede agregar los nombres a una colección de elementos denominada AvailableItemName. Por ejemplo, al agregar lo siguiente al archivo de proyecto, se agregará el tipo personalizado JScript a este menú para todos los proyectos que lo importen:

<ItemGroup>
    <AvailableItemName Include="JScript"/>
</ItemGroup>

Nota:
Algunos nombres de la colección de elementos son específicos de Visual Studio, pero no se muestran en esta lista desplegable.

Compiladores activos

Cuando sea posible, Visual Studio intentará utilizar las versiones activas de los compiladores de Visual Basic o Visual C# con el fin de mejorar el rendimiento. Para que esto funcione correctamente, se deben cumplir las condiciones siguientes:

En un destino del proyecto, debe haber una tarea denominada Csc (para proyectos de Visual C#) o Vbc (para proyectos de Visual Basic)
El parámetro UseHostCompilerIfAvailable de la tarea debe tener el valor true.
Se deben especificar sólo valores de parámetro compatibles. El compilador activo admite todos los parámetros especificados en la tarea, pero algunos valores de parámetro no son compatibles. Los siguientes valores de parámetro de la tarea Csc no son compatibles con el compilador activo de Visual C#:
- NoConfig: no se admiten false ni valores vacíos.
- ResponseFiles: no se admiten valores no vacíos.
- AdditionalLibPaths: no se admiten valores no vacíos.
- AddModules: no se admiten valores no vacíos.
- CodePage: no se admiten valores distintos de cero.
- GenerateFullPaths: no se admite true.
- LinkResources: no se admiten valores no vacíos.

Si no se cumplen estas condiciones, el proyecto compilará utilizando el compilador de la línea de comandos en lugar del compilador activo.

IntelliSense en tiempo de diseño

Para obtener compatibilidad con IntelliSense en Visual Studio antes de que una generación haya generado un ensamblado de salida, se deben cumplir las condiciones siguientes:

Debe haber un destino denominado Compile.
El destino Compile o alguna de sus dependencias deben llamar a la tarea de compilador para el proyecto, como Csc o Vbc.
El destino Compile o alguna de sus dependencias debe hacer que el compilador reciba todos los parámetros necesarios para IntelliSense, en particular todas las referencias.
Se deben cumplir las condiciones que aparecen en la sección "Compiladores activos".

Generar soluciones

En Visual Studio, el propio Visual Studio controla el archivo de solución y el orden de generación de los proyectos. Al generar una solución con msbuild.exe en la línea de comandos, MSBuild analiza el archivo de solución y ordena las generaciones del proyecto. En ambos casos, los proyectos se generan individualmente en orden de dependencia y no se recorren las referencias entre proyectos. Por el contrario, cuando los proyectos individuales se generan con msbuild.exe, se recorren las referencias entre proyectos.

Para generar en Visual Studio, la propiedad $(BuildingInsideVisualStudio) se establece en true. Esto se puede utilizar en el proyecto o en archivos .targets para que la generación se comporte de manera diferente.

Mostrar propiedades y elementos

Visual Studio reconoce algunos nombres y valores de propiedad. Por ejemplo, la propiedad siguiente de un proyecto hará que aparezca Aplicación para Windows en el cuadro Tipo de aplicación del Diseñador de proyectos.

<OutputType>WinExe</OutputType>

El valor de propiedad se puede editar en el Diseñador de proyectos y guardar en el archivo del proyecto. Si al editar la propiedad manualmente se le da un valor no válido, Visual Studio mostrará una advertencia cuando se cargue el proyecto y reemplazará el valor no válido por un valor predeterminado.

Visual Studio puede aplicar valores predeterminados a algunas propiedades. Estas propiedades no se conservarán en el archivo del proyecto a menos que tengan valores no predeterminados.

Las propiedades con nombres arbitrarios no se muestran en Visual Studio. Para modificar las propiedades arbitrarias en Visual Studio, debe abrir el archivo del proyecto en el editor XML y editarlas a mano. Para obtener más información, vea Cómo: Editar archivos de proyecto.

Los elementos definidos en el proyecto con nombres de colección de elementos arbitrarios se muestran de forma predeterminada en el Explorador de soluciones bajo su nodo de proyecto. Para ocultar un elemento, establezca los metadatos Visible en false. Por ejemplo, el elemento siguiente participará en el proceso de generación pero no se mostrará en el Explorador de soluciones.

<ItemGroup>
    <IntermediateFile Include="cache.temp">
        <Visible>false</Visible>
    </IntermediateFile>
</ItemGroup>

De forma predeterminada, no se muestran los elementos declarados en archivos importados al proyecto. Los elementos creados durante el proceso de generación nunca se muestran en el Explorador de soluciones.

Condiciones en elementos y propiedades

Durante una generación, se respetan totalmente todas las condiciones.

Al determinar los valores de propiedad que se van a mostrar, las propiedades que Visual Studio considera como dependientes de la configuración se evalúan de manera diferente que las que considera como independientes. Para las propiedades que considera como dependientes de la configuración, Visual Studio establece las propiedades Configuration y Platform de manera apropiada e indica a MSBuild que vuelva a evaluar el proyecto. En el caso de las propiedades que considera como independientes de la configuración, no importa cómo se evalúen las condiciones.

Las expresiones condicionales en los elementos siempre se omiten al decidir si el elemento debe mostrarse en el Explorador de soluciones.

Depuración

Para buscar e iniciar el ensamblado de salida y asociar el depurador, Visual Studio necesita que las propiedades OutputPath, AssemblyName y OutputType estén correctamente definidas. El depurador no podrá realizar la asociación si el proceso de generación no hiciera que el compilador generase un archivo .pdb.

Ejecución del destino en tiempo de diseño

Visual Studio intenta ejecutar los destinos con algunos nombres cuando carga un proyecto. Estos destinos incluyen Compile, ResolveAssemblyReferences, ResolveCOMReferences, GetFrameworkPaths y CopyRunEnvironmentFiles. Visual Studio los ejecuta para que el compilador pueda inicializarse con el fin de proporcionar IntelliSense, para que el depurador pueda inicializarse y las referencias mostradas en el Explorador de soluciones puedan resolverse. Si estos destinos no están presentes, el proyecto se cargará y se generará correctamente pero la experiencia en tiempo de diseño de Visual Studio no será totalmente funcional.

Editar archivos de proyecto en Visual Studio

Si es necesario editar directamente un proyecto de MSBuild, puede abrir el archivo del proyecto en el editor XML de Visual Studio. Para obtener más información, vea Cómo: Editar archivos de proyecto.

IntelliSense y validación

Al utilizar el editor XML para modificar archivos de proyecto, los archivos de esquema de MSBuild controlan la validación e IntelliSense. Visual Studio los instala en la caché del esquema, que se puede encontrar en la carpeta [ubicación de instalación de Visual Studio]\Xml\Schemas.

Los tipos básicos de MSBuild se definen en Microsoft.Build.Core.xsd y los tipos comunes utilizados por Visual Studio se definen en Microsoft.Build.CommonTypes.xsd. Para personalizar los esquemas con el fin de disponer de IntelliSense y de la validación para los nombres de la colección de elementos personalizados, propiedades y tareas, puede editar Microsoft.Build.xsd o crear su propio esquema que incluya los esquemas CommonTypes o Core. Si crea su propio esquema, tendrá que dirigir el editor XML para que lo busque mediante la ventana Propiedades.

Editar archivos de proyecto cargados

Visual Studio almacena en memoria caché el contenido de los archivos de proyecto y de los archivos importados por los archivos de proyecto. Si edita un archivo de proyecto cargado, Visual Studio pedirá automáticamente que vuelva a cargar el proyecto para que se apliquen los cambios. Sin embargo, si edita un archivo importado por un proyecto cargado, no habrá ninguna solicitud y deberá descargar y volver a cargar el proyecto manualmente para que se apliquen los cambios.

Grupos de resultados

Algunos destinos definidos en Microsoft.Common.targets tienen nombres acabados en OutputGroups u OutputGroupDependencies. Visual Studio llama a estos destinos para obtener listas específicas de los resultados del proyecto. Por ejemplo, el destino SatelliteDllsProjectOutputGroup crea una lista de todos los ensamblados satélite que creará una generación. Funciones como la publicación, la implementación y las referencias entre proyectos utilizan estos grupos de resultados. Los proyectos que no los definen se cargarán y generarán en Visual Studio, pero es posible que algunas características no funcionen correctamente.

Resolución de referencias

La resolución de referencias es el proceso de utilizar los elementos de referencia almacenados en un archivo del proyecto para buscar los ensamblados reales. Visual Studio debe desencadenar una resolución de referencias para que se muestren las propiedades detalladas de cada referencia en la ventana Propiedades. En la lista siguiente se describen los tres tipos de referencias y cómo se resuelven.

Referencias de ensamblado:

El sistema de proyectos llama a un destino con el nombre conocido de ResolveAssemblyReferences. Este destino debe generar elementos con el nombre de la colección de elementos ReferencePath. Cada uno de estos elementos debe tener una especificación de elemento (el valor del atributo Include de un elemento) que contenga la ruta completa a la referencia. Los elementos deben tener todos los metadatos de los elementos de entrada recorridos, además de los nuevos metadatos siguientes:
- CopyLocal, que indica si el ensamblado debe copiarse en la carpeta de salida, establecida en true o en false.
- OriginalItemSpec, que contiene la especificación del elemento original de la referencia.
- ResolvedFrom, establecido en "{TargetFrameworkDirectory}" si se ha resuelto en el directorio de .NET Framework.
Referencias COM:

El sistema de proyectos llama a un destino con el nombre conocido de ResolveCOMReferences. Este destino debe generar elementos con el nombre de la colección de elementos ComReferenceWrappers. Cada uno de estos elementos debe tener una especificación del elemento que contiene la ruta de acceso completa al ensamblado de interoperabilidad para obtener la referencia COM. Los elementos deben tener todos los metadatos de los elementos de entrada recorridos, además de los nuevos metadatos con el nombre CopyLocal, que indica si el ensamblado se debe copiar en la carpeta de salida, establecido en true o false.
Referencias nativas

El sistema de proyectos llama a un destino con el nombre conocido de ResolveNativeReferences. Este destino debe generar elementos con el nombre de la colección de elementos NativeReferenceFile. Los elementos deben tener todos los metadatos de los elementos de entrada recorridos, además de un nuevo fragmento de metadatos denominado OriginalItemSpec, que contiene la especificación del elemento original de la referencia.