Creación de un sistema de proyecto básico, parte 2

Artículo
03/10/2023

En el primer tutorial de esta serie, Crear un sistema de proyecto básico, parte 1, se muestra cómo crear un sistema de proyecto básico. Este tutorial se basa en el sistema de proyectos básico agregando una plantilla de Visual Studio, una página de propiedades y otras características. Debe completar el primer tutorial antes de iniciarlo.

En este tutorial se enseña a crear un tipo de proyecto que tenga la extensión de nombre de archivo del proyecto .myproj. Para completar el tutorial, no es necesario crear su propio lenguaje porque el tutorial toma prestado del sistema de proyectos de Visual C# existente.

En este tutorial se enseña a realizar estas tareas:

Cree una plantilla de Visual Studio.
Implementar una plantilla de Visual Studio.
Cree un nodo secundario de tipo de proyecto en el cuadro de diálogo Nuevo proyecto .
Habilite la sustitución de parámetros en la plantilla de Visual Studio.
Cree una página de propiedades del proyecto.

Nota:

Los pasos de este tutorial se basan en un proyecto de C#. Sin embargo, excepto para detalles como extensiones de nombre de archivo y código, puede usar los mismos pasos para un proyecto de Visual Basic.

Creación de una plantilla de Visual Studio

Crear un sistema de proyecto básico, la parte 1 muestra cómo crear una plantilla de proyecto básica y agregarla al sistema de proyectos. También se muestra cómo registrar esta plantilla con Visual Studio mediante el ProvideProjectFactoryAttribute atributo , que escribe la ruta de acceso completa de la carpeta \Templates\Projects\SimpleProject\ en el registro del sistema.

Mediante el uso de una plantilla de Visual Studio (archivo .vstemplate ) en lugar de una plantilla de proyecto básica, puede controlar cómo aparece la plantilla en el cuadro de diálogo Nuevo proyecto y cómo se sustituyen los parámetros de plantilla. Un archivo .vstemplate es un archivo XML que describe cómo se van a incluir los archivos de origen cuando se crea un proyecto mediante la plantilla del sistema de proyectos. El propio sistema de proyecto se compila mediante la recopilación del archivo .vstemplate y los archivos de origen en un archivo .zip , y se implementa copiando el archivo .zip en una ubicación conocida en Visual Studio. Este proceso se explica con más detalle más adelante en este tutorial.

En Visual Studio, abra la solución SimpleProject que creó siguiendo creación de un sistema de proyecto básico, parte 1.
En el archivo SimpleProjectPackage.cs , busque el atributo ProvideProjectFactory. Reemplace el segundo parámetro (el nombre del proyecto) por null y el cuarto parámetro (la ruta de acceso a la carpeta de plantilla de proyecto) por ".\\NullPath", como se indica a continuación.
```
[ProvideProjectFactory(typeof(SimpleProjectFactory), null,
    "Simple Project Files (*.myproj);*.myproj", "myproj", "myproj",
    ".\\NullPath",
LanguageVsTemplate = "SimpleProject")]
```
Agregue un archivo XML denominado SimpleProject.vstemplate a la carpeta \Templates\Projects\SimpleProject\ .

Reemplace el contenido de SimpleProject.vstemplate por el código siguiente.

<VSTemplate Version="2.0.0" Type="Project"
    xmlns="http://schemas.microsoft.com/developer/vstemplate/2005">
  <TemplateData>
    <Name>SimpleProject Application</Name>
    <Description>
      A project for creating a SimpleProject application
    </Description>
    <Icon>SimpleProject.ico</Icon>
    <ProjectType>SimpleProject</ProjectType>
  </TemplateData>
  <TemplateContent>
    <Project File="SimpleProject.myproj" ReplaceParameters="true">
      <ProjectItem ReplaceParameters="true" OpenInEditor="true">
        Program.cs
      </ProjectItem>
      <ProjectItem ReplaceParameters="true" OpenInEditor="false">
        AssemblyInfo.cs
      </ProjectItem>
    </Project>
  </TemplateContent>
</VSTemplate>

En la ventana Propiedades , seleccione los cinco archivos de la carpeta \Templates\Projects\SimpleProject\ y establezca la acción de compilación en ZipProject.

La <sección TemplateData> determina la ubicación y la apariencia del tipo de proyecto SimpleProject en el cuadro de diálogo Nuevo proyecto , como se indica a continuación:

El <elemento Name> asigna un nombre a la plantilla de proyecto para que sea SimpleProject Application.
El <elemento Description> contiene la descripción que aparece en el cuadro de diálogo Nuevo proyecto cuando se selecciona la plantilla de proyecto.
El <elemento Icon> especifica el icono que aparece junto con el tipo de proyecto SimpleProject.
El <elemento ProjectType> asigna un nombre al tipo Project en el cuadro de diálogo Nuevo proyecto . Este nombre reemplaza el parámetro de nombre del proyecto del atributo ProvideProjectFactory.

Nota:

El <elemento ProjectType> debe coincidir con el LanguageVsTemplate argumento del ProvideProjectFactory atributo en el archivo SimpleProjectPackage.cs.

En la <sección TemplateContent> se describen estos archivos que se generan cuando se crea un nuevo proyecto:
SimpleProject.myproj
Program.cs
Assemblyinfo.cs

Los tres archivos se han ReplaceParameters establecido en true, lo que permite la sustitución de parámetros. El archivo Program.cs se ha OpenInEditor establecido en true, lo que hace que el archivo se abra en el editor de código cuando se crea un proyecto.

Para obtener más información sobre los elementos del esquema de plantilla de Visual Studio, consulte la referencia del esquema de plantilla de Visual Studio.

Nota:

Si un proyecto tiene más de una plantilla de Visual Studio, cada plantilla se encuentra en una carpeta independiente. Cada archivo de esa carpeta debe tener la acción de compilación establecida en ZipProject.

Agregar un archivo .vsct mínimo

Visual Studio debe ejecutarse en modo de instalación para reconocer una plantilla de Visual Studio nueva o modificada. El modo de instalación requiere que haya un archivo .vsct presente. Por lo tanto, debe agregar un archivo .vsct mínimo al proyecto.

Agregue un archivo XML denominado SimpleProject.vsct al proyecto SimpleProject.

Reemplace el contenido del archivo SimpleProject.vsct por el código siguiente.

<?xml version="1.0" encoding="utf-8" ?>
<CommandTable
  xmlns="http://schemas.microsoft.com/VisualStudio/2005-10-18/CommandTable">
</CommandTable>

Establezca la acción de compilación de este archivo en VSCTCompile. Solo puede hacerlo en el archivo .csproj , no en la ventana Propiedades . Asegúrese de que la acción de compilación de este archivo está establecida en Ninguno en este momento.
1. Haga clic con el botón derecho en el nodo SimpleProject y, a continuación, haga clic en Editar SimpleProject.csproj.
2. En el archivo .csproj , busque el elemento SimpleProject.vsct .
```
<None Include="SimpleProject.vsct" />
```
3. Cambie la acción de compilación a VSCTCompile.
```
<VSCTCompile Include="SimpleProject.vsct" />
```
4. el archivo del proyecto y cierre el editor.
5. Guarde el nodo SimpleProject y, a continuación, en el Explorador de soluciones haga clic en Volver a cargar proyecto.

Examen de los pasos de compilación de plantillas de Visual Studio

El sistema de compilación del proyecto VSPackage normalmente ejecuta Visual Studio en modo de instalación cuando se cambia el archivo .vstemplate o se vuelve a generar el proyecto que contiene el archivo .vstemplate . Puede seguir estableciendo el nivel de detalle de MSBuild en Normal o superior.

En el menú Herramientas , haga clic en Opciones.
Expanda el nodo Proyectos y soluciones y, a continuación, seleccione Compilar y ejecutar.
Establezca el nivel de detalle de la salida de compilación del proyecto de MSBuild en Normal. Haga clic en OK.
Recompile el proyecto SimpleProject.

El paso de compilación para crear el archivo de proyecto .zip debe ser similar al ejemplo siguiente.

ZipProjects:
1>  Zipping ProjectTemplates
1>  Zipping <path>\SimpleProject\SimpleProject\obj\Debug\SimpleProject.zip...
1>  Copying file from "<path>\SimpleProject\SimpleProject\obj\Debug\SimpleProject.zip" to "<%LOCALAPPDATA%>\Microsoft\VisualStudio\14.0Exp\ProjectTemplates\\\\SimpleProject.zip".
1>  Copying file from "<path>\SimpleProject\SimpleProject\obj\Debug\SimpleProject.zip" to "bin\Debug\\ProjectTemplates\\\\SimpleProject.zip".
1>  SimpleProject -> <path>\SimpleProject\SimpleProject\bin\Debug\ProjectTemplates\SimpleProject.zip
1>ZipItems:
1>  Zipping ItemTemplates
1>  SimpleProject ->

Implementación de una plantilla de Visual Studio

Las plantillas de Visual Studio no contienen información de ruta de acceso. Por lo tanto, el archivo .zip de plantilla debe implementarse en una ubicación conocida para Visual Studio. La ubicación de la carpeta ProjectTemplates suele ser <%LOCALAPPDATA%>\Microsoft\VisualStudio\14.0Exp\ProjectTemplates.

Para implementar el generador de proyectos, el programa de instalación debe tener privilegios de administrador. Implementa plantillas en el nodo de instalación de Visual Studio: ...\Microsoft Visual Studio 14.0\Common7\IDE\ProjectTemplates.

Prueba de una plantilla de Visual Studio

Pruebe el generador de proyectos para ver si crea una jerarquía de proyectos mediante la plantilla de Visual Studio.

Restablezca la instancia experimental del SDK de Visual Studio.

En Windows 7: en el menú Inicio , busque la carpeta Microsoft Visual Studio/Microsoft Visual Studio SDK/Tools y, a continuación, seleccione Restablecer la instancia experimental de Microsoft Visual Studio.

En versiones posteriores de Windows: en la pantalla Inicio, escriba Restablecer la versión> experimental de Microsoft Visual Studio<.
Aparece una ventana del símbolo del sistema. Cuando vea las palabras Presione cualquier tecla para continuar, haga clic en ENTRAR. Después de cerrar la ventana, abra Visual Studio.
Recompile el proyecto SimpleProject e inicie la depuración. Aparece la instancia experimental.
En la instancia experimental, cree un proyecto SimpleProject. En el cuadro de diálogo Nuevo proyecto , seleccione SimpleProject.
Debería ver una nueva instancia de SimpleProject.

Creación de un nodo secundario de tipo de proyecto

Puede agregar un nodo secundario a un nodo de tipo de proyecto en el cuadro de diálogo Nuevo proyecto . Por ejemplo, para el tipo de proyecto SimpleProject, podría tener nodos secundarios para aplicaciones de consola, aplicaciones de ventana, aplicaciones web, etc.

Los nodos secundarios se crean modificando el archivo del proyecto y agregando <elementos secundarios OutputSubPath> a los <elementos ZipProject> . Cuando se copia una plantilla durante la compilación o implementación, cada nodo secundario se convierte en una subcarpeta de la carpeta plantillas de proyecto.

En esta sección se muestra cómo crear un nodo secundario de consola para el tipo de proyecto SimpleProject.

Cambie el nombre de la carpeta \Templates\Projects\SimpleProject\ a \Templates\Projects\ConsoleApp\.
En la ventana Propiedades , seleccione los cinco archivos de la carpeta \Templates\Projects\ConsoleApp\ y asegúrese de que la acción de compilación esté establecida en ZipProject.
En el archivo SimpleProject.vstemplate, agregue la siguiente línea al final de la <sección TemplateData> , justo antes de la etiqueta de cierre.
```
<NumberOfParentCategoriesToRollUp>1</NumberOfParentCategoriesToRollUp>
```
Esto hace que la plantilla Aplicación de consola aparezca en el nodo secundario Consola y en el nodo primario SimpleProject, que es un nivel por encima del nodo secundario.
Guarde el archivo SimpleProject.vstemplate .
En el archivo .csproj , agregue <OutputSubPath> a cada uno de los elementos ZipProject. Descargue el proyecto, como antes, y edite el archivo del proyecto.

Busque los <elementos ZipProject> . Para cada <elemento ZipProject> , agregue un <elemento OutputSubPath> y asígnele el valor Console. The ZipProject

<ZipProject Include="Templates\Projects\ConsoleApp\AssemblyInfo.cs">
  <OutputSubPath>Console</OutputSubPath>
</ZipProject>
<ZipProject Include="Templates\Projects\ConsoleApp\Program.cs">
  <OutputSubPath>Console</OutputSubPath>
</ZipProject>
<ZipProject Include="Templates\Projects\ConsoleApp\SimpleProject.myproj">
  <OutputSubPath>Console</OutputSubPath>
</ZipProject>
<ZipProject Include="Templates\Projects\ConsoleApp\SimpleProject.vstemplate">
  <OutputSubPath>Console</OutputSubPath>
</ZipProject>
<ZipProject Include="Templates\Projects\ConsoleApp\SimpleProject.ico">
  <OutputSubPath>Console</OutputSubPath>
</ZipProject>

Agregue este <PropertyGroup> al archivo del proyecto:

<PropertyGroup>
  <VsTemplateLanguage>SimpleProject</VsTemplateLanguage>
</PropertyGroup>

Guarde el archivo del proyecto y vuelva a cargar el proyecto.

Prueba del nodo secundario de tipo de proyecto

Pruebe el archivo de proyecto modificado para ver si el nodo secundario Consola aparece en el cuadro de diálogo Nuevo proyecto .

Ejecute la herramienta Restablecer la instancia experimental de Microsoft Visual Studio.
Recompile el proyecto SimpleProject e inicie la depuración. Debería aparecer la instancia experimental.
En el cuadro de diálogo Nuevo proyecto , haga clic en el nodo SimpleProject . La plantilla Aplicación de consola debe aparecer en el panel Plantillas .
Expanda el nodo SimpleProject . Debería aparecer el nodo secundario Consola . La plantilla Aplicación SimpleProject sigue apareciendo en el panel Plantillas .
Haga clic en Cancelar y detenga la depuración.

Sustituir parámetros de plantilla de proyecto

Al crear un sistema de proyecto básico, la parte 1 mostró cómo sobrescribir el ProjectNode.AddFileFromTemplate método para realizar un tipo básico de sustitución de parámetros de plantilla. En esta sección se enseña a usar los parámetros de plantilla de Visual Studio más sofisticados.

Al crear un proyecto mediante una plantilla de Visual Studio en el cuadro de diálogo Nuevo proyecto, los parámetros de plantilla se reemplazan por cadenas para personalizar el proyecto. Un parámetro de plantilla es un token especial que comienza y termina con un signo de dólar, por ejemplo, $time$. Los dos parámetros siguientes son especialmente útiles para habilitar la personalización en proyectos basados en la plantilla:

$GUID[1-10]$ se reemplaza por un nuevo GUID. Puede especificar hasta 10 GUID únicos, por ejemplo, $guid 1$.
$safeprojectname$ es el nombre proporcionado por un usuario en el cuadro de diálogo Nuevo proyecto , modificado para quitar todos los caracteres y espacios no seguros.

Para obtener una lista completa de parámetros de plantilla, vea Parámetros de plantilla.

Para sustituir parámetros de plantilla de proyecto

En el archivo SimpleProjectNode.cs , quite el AddFileFromTemplate método .
En el archivo \Templates\Projects\ConsoleApp\SimpleProject.myproj , busque la <propiedad RootNamespace> y cambie su valor a $safeprojectname$.
```
<RootNamespace>$safeprojectname$</RootNamespace>
```

En el archivo \Templates\Projects\SimpleProject\Program.cs , reemplace el contenido del archivo por el código siguiente:

using System;
using System.Collections.Generic;
using System.Text;
using System.Runtime.InteropServices;    // Guid

namespace $safeprojectname$
{
    [Guid("$guid1$")]
    public class $safeprojectname$
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello VSX!!!");
            Console.ReadKey();
        }
    }
}

Recompile el proyecto SimpleProject e inicie la depuración. Debería aparecer la instancia experimental.
Cree una nueva aplicación simpleProject Console. (En Panel Tipos de proyecto, seleccione SimpleProject. En Plantillas instaladas de Visual Studio, seleccione Aplicación de consola).

En el proyecto recién creado, abra Program.cs. Debe tener un aspecto similar al siguiente (los valores GUID del archivo variarán).

using System;
using System.Collections.Generic;
using System.Text;
using System.Runtime.InteropServices;    // Guid

namespace Console_Application1
{
    [Guid("00000000-0000-0000-00000000-00000000)"]
    public class Console_Application1
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello VSX!!!");
            Console.ReadKey();
        }
    }
}

Crear una página de propiedades del proyecto

Puede crear una página de propiedades para el tipo de proyecto para que los usuarios puedan ver y cambiar las propiedades de los proyectos basados en la plantilla. En esta sección se muestra cómo crear una página de propiedades independiente de la configuración. Esta página de propiedades básica usa una cuadrícula de propiedades para mostrar las propiedades públicas que expone en la clase de página de propiedades.

Derive la clase de página de propiedades de la SettingsPage clase base. La cuadrícula de propiedades proporcionada por la SettingsPage clase es consciente de la mayoría de los tipos de datos primitivos y sabe cómo mostrarlos. Además, la SettingsPage clase sabe cómo conservar los valores de propiedad en el archivo del proyecto.

La página de propiedades que cree en esta sección le permite modificar y guardar estas propiedades del proyecto:

AssemblyName
OutputType
RootNamespace.

En el archivo SimpleProjectPackage.cs , agregue este ProvideObject atributo a la SimpleProjectPackage clase :
```
[ProvideObject(typeof(GeneralPropertyPage))]
public sealed class SimpleProjectPackage : ProjectPackage
```
Esto registra la clase GeneralPropertyPage de página de propiedades con COM.

En el archivo SimpleProjectNode.cs , agregue estos dos métodos invalidados a la SimpleProjectNode clase :

protected override Guid[] GetConfigurationIndependentPropertyPages()
{
    Guid[] result = new Guid[1];
    result[0] = typeof(GeneralPropertyPage).GUID;
    return result;
}
protected override Guid[] GetPriorityProjectDesignerPages()
{
    Guid[] result = new Guid[1];
    result[0] = typeof(GeneralPropertyPage).GUID;
    return result;
}

Ambos métodos devuelven una matriz de GUID de página de propiedades. El GUID generalPropertyPage es el único elemento de la matriz, por lo que el cuadro de diálogo Páginas de propiedades mostrará solo una página.

Agregue un archivo de clase denominado GeneralPropertyPage.cs al proyecto SimpleProject.

Reemplace el contenido de este archivo mediante el código siguiente:

using System;
using System.Runtime.InteropServices;
using Microsoft.VisualStudio;
using Microsoft.VisualStudio.Project;
using System.ComponentModel;

namespace SimpleProject
{
    [ComVisible(true)]
    [Guid("6BC7046B-B110-40d8-9F23-34263D8D2936")]
    public class GeneralPropertyPage : SettingsPage
    {
        private string assemblyName;
        private OutputType outputType;
        private string defaultNamespace;

        public GeneralPropertyPage()
        {
            this.Name = "General";
        }

        [Category("AssemblyName")]
        [DisplayName("AssemblyName")]
        [Description("The output file holding assembly metadata.")]
        public string AssemblyName
        {
            get { return this.assemblyName; }
        }
        [Category("Application")]
        [DisplayName("OutputType")]
        [Description("The type of application to build.")]
        public OutputType OutputType
        {
            get { return this.outputType; }
            set { this.outputType = value; this.IsDirty = true; }
        }
        [Category("Application")]
        [DisplayName("DefaultNamespace")]
        [Description("Specifies the default namespace for added items.")]
        public string DefaultNamespace
        {
            get { return this.defaultNamespace; }
            set { this.defaultNamespace = value; this.IsDirty = true; }
        }

        protected override void BindProperties()
        {
            this.assemblyName = this.ProjectMgr.GetProjectProperty("AssemblyName", true);
            this.defaultNamespace = this.ProjectMgr.GetProjectProperty("RootNamespace", false);

            string outputType = this.ProjectMgr.GetProjectProperty("OutputType", false);
            this.outputType = (OutputType)Enum.Parse(typeof(OutputType), outputType);
        }

        protected override int ApplyChanges()
        {
            this.ProjectMgr.SetProjectProperty("AssemblyName", this.assemblyName);
            this.ProjectMgr.SetProjectProperty("OutputType", this.outputType.ToString());
            this.ProjectMgr.SetProjectProperty("RootNamespace", this.defaultNamespace);
            this.IsDirty = false;

            return VSConstants.S_OK;
        }
    }
}

La GeneralPropertyPage clase expone las tres propiedades públicas AssemblyName, OutputType y RootNamespace. Dado que AssemblyName no tiene ningún método set, se muestra como una propiedad de solo lectura. OutputType es una constante enumerada, por lo que aparece como lista desplegable.

La SettingsPage clase base proporciona ProjectMgr para conservar las propiedades. El BindProperties método usa ProjectMgr para recuperar los valores de propiedad persistentes y establecer las propiedades correspondientes. El ApplyChanges método usa ProjectMgr para obtener los valores de las propiedades y conservarlos en el archivo del proyecto. El método de conjunto de propiedades establece en IsDirty true para indicar que las propiedades deben conservarse. La persistencia se produce al guardar el proyecto o la solución.

Recompile la solución SimpleProject e inicie la depuración. Debería aparecer la instancia experimental.
En la instancia experimental, cree una nueva aplicación SimpleProject.
Visual Studio llama a la factoría de proyectos para crear un proyecto mediante la plantilla de Visual Studio. El nuevo archivo Program.cs se abre en el editor de código.
Haga clic con el botón derecho en el nodo del proyecto en Explorador de soluciones y, a continuación, haga clic en Propiedades. Se muestra el cuadro de diálogo Páginas de propiedades.

Probar la página de propiedades del proyecto

Ahora puede probar si puede modificar y cambiar los valores de propiedad.

En el cuadro de diálogo Páginas de propiedades de MyConsoleApplication, cambie DefaultNamespace a MyApplication.
Seleccione la propiedad OutputType y, a continuación, seleccione Biblioteca de clases.
Haga clic en Aplicar y, a continuación, en Aceptar.
Vuelva a abrir el cuadro de diálogo Páginas de propiedades y compruebe que los cambios se han conservado.
Cierre la instancia experimental de Visual Studio.
Vuelva a abrir la instancia experimental.
Vuelva a abrir el cuadro de diálogo Páginas de propiedades y compruebe que los cambios se han conservado.
Cierre la instancia experimental de Visual Studio.