Cómo Utilizar Bootstrap y Crear Proyectos .NET

BY ANDREI SMIRNOV - FREELANCE SOFTWARE ENGINEER @ TOPTAL(TRANSLATED BY MARISELA ORDAZ)

Link original del artículo: Aquí

#bootstrapping #create #DotNet #projects
This article was originally written in English

Crea un Proyecto .NET

Para crear un proyecto .NET desde cero es tan fácil como usar Visual Studio wizard. Ve a File => New Project, o Add New Project para una solución ya existente. Una vez que se ha creado un nuevo proyecto, puedes comenzar a codificar de inmediato. Sin embargo, las configuraciones predeterminadas del proyecto producidas por wizards son poco aceptadas por equipos profesionales ya que bajan la calidad general. Más aún, ningún otro wizards puede saber sobre otros pasos de configuración que debes realizar en ambiente de desarrollo particular.

En este artículo, te guiaré por varias configuraciones importantes que deberías habilitar al momento de crear un nuevo proyecto, lo cual es importante para minimizar una deuda técnica futura. También vamos a revisar algunas prácticas comunes los desarrolladores .NET aplican al estructurar soluciones y nuevos proyectos. Aunque no estés aplicando algunas de estas ideas, es bueno aprender y ver un resumen de lo que hacen la mayoría de estos equipos.

Estructura

Tener una estructura bien definida es vital para proyectos complejos. Esto mejora la experiencia de ingreso para los nuevos miembros que se unen al equipo, también hace tu vida más fácil cuando respaldas viejos proyectos. Hay dos indicadores clave en una buena estructura:

• Usar carpetas de proyecto y solución
• Dar nombres constantemente

Archivos

Carpetas de solución, a veces se le refiere como carpetas virtuales, son un instrumento muy útil para agrupar tus proyectos. En la vista Solución Explorer solo das clic derecho y seleccionas Agregar => Nueva Carpeta de Solución, luego arrastras y sueltas cualquiera de los proyectos existentes a esta nueva carpeta. Estas carpetas no tienen copias en el sistema de archivos, esto te permite mantener la estructura física sin cambio alguno, así que al mover los proyectos de una Carpeta de Solución a otra, en realidad, no se mueven físicamente.

Tener prefijos enumerados no es necesario, pero tener las carpetas ordenadas en la ventana Solución Explorer, sí lo es.

Estudio Visual puede trabajar con soluciones múltiples al mismo tiempo al aprovechar los modelos Únicas Soluciones Particionadas o Multi-solución. Raramente se usan, así que no hablaré de ellas en este artículo.

A diferencia de Carpetas de Solución, Carpetas de Proyecto une la estructura de la carpeta física y por consiguiente, persiste como carpetas reales en el disco. Más aún, las carpetas de Proyecto que contienen un código C# deberían coincidir con el espaciodenombres. Esto hace a la navegación muy natural. Puedes habilitar una regla ReSharper para que advierta sobre estas incompatibilidades.

Nombrar

Hay pocas reglas recomendadas relacionadas con nombrar:

• Usa CamelCase.
• Un nombre de proyecto debería coincidir con su nombre de ensamblaje de salida.
• Un proyecto que contenga pruebas automatizadas, debería tener el sufijo .Tests.
• Todos los nombres de proyectos deberían tener un sufijo común, como Company.Product.

También hay algunas reglas razonables. Deberías decidir por ti mismo cuando aplicarlas, basado en sentido común (y gramática, por supuesto):

• Usa sujetos en forma plural cuando un contenedor (proyecto o carpeta) contiene instancias múltiples del mismo tipo (ej. Tests o System.Collections).
• Usa forma singular cuando todo el contenedor contenga código sobre una sola entidad (ej. Sistema.Colecciones.ModeloObjeto`).
• Para abreviaciones cortas, usa mayúscula como hace System.IO.
• Para abreviaciones largas, usa CamelCase como Modules.Forex..

Una regla fija: una abreviación corta no debería tener más de tres caracteres.

Solución de Configuración

Configurar una solución es tan simple como proveer todos los archivos de infraestructura que necesitas para tu ambiente. Aunque algunos de ellos pueden ser añadidos después (como archivos de integración CI), deberías tener pocos archivos en el comienzo.

Configuraciones ReSharper

Si eres un desarrollador .NET profesional, entonces probablemente uses ReSharper. ReSharper es muy flexible al manejar sus configuraciones. Como líder de equipo, puedes crear y distribuir configuraciones *Team Shared* que serán usadas por otros desarrolladores. Las configuraciones *Team Shared* son almacenadas en un archivo con extensión .DotSettings. ReSharper escogerá estas configuraciones automáticamente si el nombre del archivo coincide con el nombre solución de Visual Studio:

MyCompany.MyProduct.sln
MyCompany.MyProduct.sln.DotSettings

Por esto, deberías crear este archivo en el comienzo si quieres aplicar algunas configuraciones a todo el equipo. Un buen ejemplo puede ser la regla de usar (o no usar) la clave var. Tu archivo de configuración Team Shared puede tener solo esta regla, mientras que otros son la preferencia de los desarrolladores. Vale la pena mencionar que de la misma forma en que las configuraciones ReSharper se pueden establecer en un nivel por proyecto, porque puedes tener un código de legado que no puedes modificar (ej. Cambio para usar la clave var).

Si nombraste este archivo correctamente, como se muestra en el ejemplo, entonces toda nueva instancia de Visual Studio con una nueva instalación de ReSharper escogerá este archivo automáticamente e impondrá las reglas. No olvides comprometer este archivo al control de fuente.

Reglas StyleCop

Al igual que con las configuraciones ReSharper, puedes compartir las configuraciones StyleCop. Si usas ReSharper, entonces debes tener el plugin de integración instalado, eso le dará ventaja a StyleCop sobre ReSharper. Sin embargo, StyleCop almacena sus configuraciones independientemente en archivos llamados Settings.StyleCop. Similarmente, puede tener este archivo con un archivo de solución y archivos de proyecto.

Si estás usando StyleCop, no olvides ejecutar la herramienta de configuración StyleCop y deshabilitar los chequeos que no quieres hacer. Por defecto, todos los chequeos están habilitados. Guarda nuevas configuraciones en este archivo y compromételas al código fuente.

Archivos de Texto

Si estás construyendo un producto público y vas a publicar el código fuente, no olvides crear y comprometer estos archivos también:

README.md
LICENSE

Recomiendo usar el formato markdown para el archivo README.md, porque se convirtió un estándar industrial, apoyada por servicios de control de fuente público como GitHub, como también servidores internos como BitBucket (antiguo Stash).

Especificaciones NuGet

Si estás construyendo una biblioteca, la cual se distribuirá en la Galería NuGet, entonces, probablemente necesites crear archivos de paquetes de especificación, como MyProject.nuspec. Yo prefiero crear estos paquetes manualmente y comprometerlos al control de fuente. Los paquetes normalmente se hacen públicos por uno de tus trabajos de Integración Continua (IC abreviado), pero también en cualquier momento puedes construir y publicar un paquete desde la consola, manualmente, como se ve a continuación:

nuget.exe pack MyLibrary.nuspec

No olvides incrementar la versión del paquete antes de ejecutar este comando.

Archivos IC Específicos

Todos usamos servicios IC diferentes, y todos tienen diferentes scripts de configuración y ajustes. Yo mencionaría algunas adiciones comunes que puedes considerar agregar:

• Configuraciones NUnit, especifica que ensamblajes contienen tests para ser ejecutados en servidor IC para trabajos particulares. Todos los tests están prácticamente divididos en algunas categorías. Hay tests de unidad que se deberían ejecutar en cada construcción, tests de desempeño que se ejecutan todas las noches, y tests de integración se ejecutan en cada lanzamiento.
• Configuraciones NCover, especifica que ensamblajes de tests deberían ser analizados para cobertura de test.
• Configuración SonarQube, determina que las métricas de software serán recolectadas.
• Scripts de Trabajo, tales como NAnt, PowerShell o simplemente archivos por lote de Windows.

Proyectos apropiadamente hechos por ti mismo disminuyen la deuda técnica futura y hace al código fuente de un producto, leíble y de aspecto profesional.

Configurar Proyectos

Archivos de proyecto, namely .csproj o .vbpro, contienen todas las configuraciones usadas por Visual Studio y MSBuild. Sin embargo, no todos ellos están disponibles en la ventana Project Properties. Para editar estos archivos en Visual Studio manualmente, deberías hacer lo siguiente:

• Dale clic derecho a un proyecto en vista Solution Explorer.
• Selecciona Unload Project .
• Dale clic derecho nuevamente para escoger la acción_Edit xyz.csproj_.
• Completa la edición.
• Dale clic derecho en el proyecto nuevamente, y escoge Reload Project.

Alternativamente, puedes abrir un archivo de proyecto en tu editor de texto favorito, edítalo y guárdalo. Cuando regresas a la ventana Visual Studio, se te sugerirá que vuelvas a cargar el proyecto cambiado.

Advertencias de Control

Construir un software de alta calidad requiere que nunca ignores las advertencias de construcción. Por esto, deberías habilitar el nivel máximo de advertencias y tratar cualquier advertencia como error. Nota que deberías hacer esto con todas las configuraciones de construcción que tengas como Debug y Release. La mejor manera de hacer esto es escribir las siguientes configuraciones al grupo de propiedad común:

<WarningLevel>4</WarningLevel>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>

Y asegúrate de que no tengas las mismas configuraciones de otros grupos de propiedad común. Sino, anularán las propiedades correspondientes del grupo común.

FxCop

Ejecutar FxCop solo es práctico hacerlo en cada construcción. La mayoría de los equipos prefieren ejecutar FxCop de vez en cuando (usualmente antes de un lanzamiento) para asegurarse que no se introdujeron errores severos. Sin embargo, si quieres hacer chequeos óptimos en cada construcción, agrega esta opción:

<RunCodeAnalysis>true</RunCodeAnalysis>

Nota que FxCop, como StyleCop, tiene sus propias configuraciones, las cuales se pueden colocar en la carpeta raíz y agregarse al control de fuente. Estas configuraciones se usan, posiblemente, al ejecutar FxCop en servidores CI.

Documentación

Esta parte es sobre XmlDoc. Si estás construyendo una API pública, entonces deberías crear y mantener documentación API. La mayoría de los desarrolladores comienzan con desarrollo API (codificación real), y justo antes de un lanzamiento habilitan la codificación de proyecto Build / XML documentation file. Naturalmente, después de otra reconstrucción aparecen un montón de errores, porque cada XmlDoc faltante resulta en error de construcción. Para evitar esto, deberías habilitar la opción mencionada desde el comienzo.

Si eres muy flojo para escribir una documentación apropiada o no te gusta transcribir mucho texto, usa instrumentos que automatizan este proceso, como GhostDoc.

Contratos de Código

Contratos de Código es un excelente marco de Microsoft Research, el cual te ayuda a expresar pre-condiciones e invariantes de objeto en tu código para tiempo de ejecución, chequeo, análisis estático y documentación. Yo lo usé en muchos proyectos críticos y me ayudó mucho, así que te animo a que lo pruebes.

Si decides usar Contratos de Código, entonces es importante habilitar Contratos desde el comienzo. Agregar Contratos a la mitad del desarrollo es posible, pero requerirá cambios a través de muchas clases, para hacer que los Contratos compaginen entre sí. Así que no olvides habilitar todas las configuraciones requeridas (al menos CodeContractsEnableRuntimeChecking) y asegúrate de que estas configuraciones aparezcan en el grupo de propiedad común.

Aplicación StyleCop

Previamente hablamos sobre la configuración StyleCop para tiempo de desarrollo. Sin embargo, cuando tu proyecto está construido en un servidor CI, ReSharper no tiene ningún efecto ahí y por esto deberíamos habilitar la validación StyleCop para ejecutarse con MSBuild.

Usualmente esto se hace por modificación del archivo de proyecto. Necesitas descargar el proyecto en Visual Studio, editar el archivo de proyecto y luego cargar de nuevo el proyecto:

<PropertyGroup>
  <!— agrega esto al grupo de propiedad común (común para Debug/Release/etc) —>
  <StyleCopTreatErrorsAsWarnings>false</StyleCopTreatErrorsAsWarnings>
</PropertyGroup>

<!— agrega esta Importación en la parte baja —>
<Import Project="$(ProgramFiles)\MSBuild\Microsoft\StyleCop\v4.3\Microsoft.StyleCop.targets">

La configuración StyleCopTreatErrorsAsWarnings hará lo que dice: romperá tu construcción por cualquier violación de una regla StyleCop. El elemento de importación es requerido por MSBuild para agregar una prueba StyleCop a la cadena de construcción.

Habrás notado el camino a Program Files. Porque los desarrolladores pueden tener diferentes versiones instaladas de StyleCop, algunos equipos prefieren mantener una copia privada de la misma instalación StyleCop bajo el control de fuente. En este caso, el camino será relativo. Esto también hace que la instalación de las máquinas CI sea más fácil, ya que no necesitas instalar StyleCop localmente.

AssemblyInfo

Todo proyecto .NET creado por el wizard Visual Studio tendrá el archivo AssemblyInfo.cs poblado automáticamente (mira Properties subfolder) el cual contiene algunos atributos Assembly, pero ningún wizard puede llenar todos los atributos Assembly por ti. Asegúrate de tener al menos estos atributos poblados:

• AssemblyTitle
• AssemblyDescription
• AssemblyCompany
• AssemblyProduct
• AssemblyCopyright
• AssemblyVersion

Esto es lo mínimo que se requiere para cualquier ensamblado que vayas a distribuir. Una razón práctica detrás de esto es NuGet: si estás usando NuGet automático para creación específica del archivo de ensamblaje, esta herramienta te dará información necesaria de estas propiedades.

También puedes poblar una propiedad más desde el comienzo:

InternalsVisibleTo

Esta propiedad hace visible las clases internas e interfaces al ensamblaje específico. Esto se usa generalmente para tests automatizados que crearás para tu proyecto.

Cadenas de Conexión

Como manejar cadenas de conexión es una pregunta muy popular en Stack Overflow. El problema es cómo hacer la cadena de conexión única para cada desarrollador o trabajo CI, y no exponer detalles de conexión mientras se publica el código fuente.

En App.config (para aplicaciones de escritorio) o Web.config (para aplicaciones web), haz la siguiente configuración que estará cargando el archivo user.config en el tiempo de ejecución. Ten esto en tu control de fuente:


<configuration>
	<connectionStrings configSource="user.config"></connectionStrings>
</configuration>

Al parecer el archive user.config debería estar excluído del control de fuente y cada desarrollador debería tener una copia local de este archivo, así se preservará la privacidad de la cadena de conexión:


<connectionStrings>
	<add name="test" connectionString="Server=.;Database=...;"/>
</connectionStrings>

.gitignore

Para aquellos que usan Git como control de fuente es importante agregar algunos patrones de archivo al archivo .gitignore . Sin embargo, nuestra comunidad inteligente ya ha hecho un archivo general el cual puedes encontrar aquí: github.com/github/gitignore/blob/master/VisualStudio.gitignore.

Deberías tomarlo como un archivo de referencia .gitignore y simplemente agregar las exclusiones personalizadas que puedas necesitar.

Insignias GitHub

Tal vez habrás visto unas insignias muy buenas en la página README del proyecto. Si vas a publicar tu proyecto en GitHub, puede que quieras conectar tu proyecto a los servicios públicos:

• Construyendo: para mostrar un proyecto que está fallando o pasando.
• Testing: para mostrar la cobertura de un test y el estado de ejecución de un test.
• Publicando: para mostrar la última versión de paquete de NuGet.

Puedes ver una lista completa de insignias y servicios relacionados en shields.io. Puede ser que encuentres varias insignias que son buenas para proyectos de Código Abierto.

Una vez te hayas registrado para tu proyecto con un servicio específico te darán un link a la imagen y un link para la sintaxis completa del markdown, los cuales puedes agregar a tu archivo README.md . Por cierto, esta es una de las razones por las que deberías preferir markdown a archivos Readme .

Insignias markdown de muestra del proyecto Roslyn:

[![Construir Estado]([http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/badge/icon)](http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/)](http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/badge/icon)](http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/))

[![Unete al chat aquí [https://gitter.im/dotnet/roslyn](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dotnet/roslyn?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)](https://gitter.im/dotnet/roslyn](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dotnet/roslyn?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge))

Validación Automática De Solución De La Estructura

A pesar de que has establecido todas las configuraciones que se explicaron en este artículo en algún momento algunos de tus desarrolladores podría cambiarlas y guardar los cambios en la fuente de control. Algunas veces esto sucede por error y por lo general estos cambios no se ven cuando se revisa el código. A parte de estos accidentes, deberíamos estar pendientes de los siguientes errores:

• Malas referencias: cuando se hace referencia a un ensamblador local que otros no tengan o cuando alguien borra un archivo del disco, mientras que el link a dicho archivo continúa en el archivo .csproj . Esto seguramente hará que la construcción no funcione pero puede que suceda muy tarde, una vez que los cambios fueron hechos y otros los usaron. Esto es algo esencial en archivos de web estática, los cuales no puedes verificar durante la construcción.
• Nomenclatura de Consistencia: herramientas como StyleCop pueden controlar código fuente C# pero ninguna herramienta puede forzar reglas para archivos Project o propiedades Assembly. Un buen ejemplo de esto es: Queremos nombrar proyectos que coincidan con el nombre de salida ensamblado y queremos nombres de proyectos que tengan prefijos en común, como: MiCompañía.MiProducto.

En ocasiones he encontrado que ver estos errores en Revisiones de Código es propenso a más errores y debería ser automatizado. Es por ello que escribe una herramienta sencilla que hace esto y también otras revisiones para verificar que la solución de consistencia. Conoce a SolutionInspector. Es Código Abierto y es distribuido bajo licencia de MIT. Puedes construirlo desde el código fuente o instalarlo por NuGet:

Install-Package SolutionInspector

La herramienta te muestra toda la estructura de solución y aplica muchas de las reglas de validación. Las reglas están configuradas en archivos XML a lo largo de otros archivos de solución. Para controlar las configuraciones en las bases de cada proyecto solo tienes que agregar el mismo archivo pero con una configuración diferente a la carpeta de proyecto correspondiente.

No se necesita un archivo de configuración por defecto. En este caso la herramienta aplicará todas las reglas disponibles y luego generará todos los problemas existentes a la consola.

Aquí puedes ver un ejemplo del archivo de configuración:



<Settings xmlns:xsi="[http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">](http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">)

<SolutionSettings>
   <MinSolutionFormatVersion>12.00</MinSolutionFormatVersion>
   <MaxSolutionFormatVersion>12.00</MaxSolutionFormatVersion>
   <DetectMissingFiles>true</DetectMissingFiles>
   <ProjectNamePrefix>MyCompany.MyProduct.</ProjectNamePrefix>
   <ProjectNameIsFileName>true</ProjectNameIsFileName>
   <IgnoredProjects>
       AVerySpecialProject1;
       AVerySpecialProject2;
   </IgnoredProjects>
</SolutionSettings>

<ProjectSettings>
   <DetectMissingFiles>true</DetectMissingFiles>
   <AllowBuildEvents>true</AllowBuildEvents>
   <AssemblyNameIsProjectName>true</AssemblyNameIsProjectName>
   <RootNamespaceIsAssemblyName>true</RootNamespaceIsAssemblyName>
   <RequiredImports>StyleCop.MSBuild.Targets</RequiredImports>
   <Properties>
       <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
       <StyleCopTreatErrorsAsWarnings>false</StyleCopTreatErrorsAsWarnings>
   </Properties>
</ProjectSettings>

</Settings>

Aunque las configuraciones son específicos de igual forma explicaré algunos a continuación:

• MinSolutionFormatVersion / MaxSolutionFormatVersion esto hará que los desarrolladores cambien la versión de Visual Studio.
• DetectMissingFiles es muy útil para contenido de web estática u otros archivos sin código que se agreguen a la solución o al proyecto.
• AllowBuildEvents puede evitar que se añadan eventos personalizados de construcción, que podrían hacer cosas innecesarias.
• Properties es el elemento más flexible: puedes chequear cualquier propiedad en contra de valores deseados, así los valores sean propiedades conocidas o personalizadas.

Conclusión

Hemos revisado varias prácticas estándares, archivos de configuración y configuraciones de proyecto que puedes aplicar cuando estás empezando un nuevo proyecto. Hacer esto cuando recién estás iniciando podría disminuir cualquier deuda técnica en el futuro y hará que tu proyecto de código fuente se vea bien y parezca profesional. Para un proyecto de Código Abierto, esto es particularmente importante debido a que cualquier colaborador podría conocer tus experiencias al examinar las configuraciones de solución y los archivos de proyecto.