Como inicializar e criar projetos .NET

Criar projeto .NET

Para criar um projeto .NET do zero é tão simples quanto usar o assistente do Visual Studio. Vá para File => New Project ou Add New Project a uma solução existente. Uma vez que um novo projeto foi criado, você pode começar a codificar imediatamente. No entanto, as configurações de projeto padrão produzidas por assistentes dificilmente são aceitáveis ​​para equipes profissionais, porque definem um nível muito baixo de qualidade. Além disso, nenhum assistente pode saber sobre outras etapas de configuração que você precisa executar em seu ambiente de desenvolvimento específico.

Neste artigo, mostrarei várias configurações importantes que você deve habilitar assim que criar um novo projeto, o que é importante para minimizar uma dívida técnica futura. Além disso, revisaremos algumas práticas comuns que muitos desenvolvedores .NET aplicam quando estão estruturando soluções e novos projetos. Mesmo que você não esteja aplicando algumas dessas ideias, é bom aprender e ter uma visão geral do que a maioria das equipes faz.

Estrutura

Ter uma estrutura bem definida é vital para projetos complexos. Isso melhora a experiência de integração quando os recém-chegados estão ingressando em uma equipe e facilita sua vida quando você apoia projetos antigos. Existem dois indicadores-chave de uma boa estrutura:

• Usando pastas de soluções e projetos
• Nomenclatura consistente

Pastas

As pastas de soluções, às vezes chamadas de pastas virtuais , são um instrumento muito útil para agrupar seus projetos. Na visualização Solution Explorer , basta clicar com o botão direito do mouse e selecionar Add => New Solution Folder e, em seguida, arrastar e soltar qualquer um dos projetos existentes para esta nova pasta. Essas pastas não são espelhadas no sistema de arquivos, permitindo que você mantenha a estrutura física inalterada, portanto, mover os projetos de uma Pasta de Solução para outra não os move fisicamente.

Não é necessário ter prefixos numerados, mas está fazendo com que as pastas apareçam ordenadas diretamente na janela do Solution Explorer .

O Visual Studio pode trabalhar com várias soluções ao mesmo tempo, aproveitando a solução única particionada ou os modelos de várias soluções . Eles raramente são usados, então não vou abordá-los neste artigo.

Ao contrário das pastas Solution , as pastas do Project correspondem à estrutura de pastas físicas e, portanto, persistem como pastas reais no disco. Além disso, as pastas do projeto contendo um código C# devem corresponder ao namespace do projeto. Isso torna a navegação bastante natural. Você pode até habilitar uma regra do ReSharper para avisar sobre essas incompatibilidades.

Nomeação

Existem algumas regras recomendadas a serem aplicadas relacionadas à nomenclatura:

• Use CamelCase.
• Um nome de projeto deve corresponder ao nome do assembly de saída.
• Um projeto contendo testes automatizados deve ter o sufixo .Tests .
• Todos os nomes de projeto devem ter um prefixo comum, como Company.Product .

Existem algumas regras razoáveis ​​também. Você deve decidir por conta própria quando aplicá-los com base no bom senso (e gramática inglesa, é claro):

• Use assuntos no plural quando um contêiner (projeto ou pasta) contiver várias instâncias do mesmo tipo (por exemplo, Tests ou System.Collections ).
• Use a forma singular quando todo o contêiner contém código sobre uma única entidade (por exemplo, System.Collections.ObjectModel`).
• Para abreviações curtas, use maiúsculas como System.IO .
• Para abreviações longas, use CamelCase como Modules.Forex. .

Uma regra prática: uma abreviatura curta não deve ter mais de três caracteres.

Configurando a solução

Configurar uma solução é tão simples quanto fornecer todos os arquivos de infraestrutura necessários para o seu ambiente. Embora alguns deles possam ser adicionados posteriormente (como arquivos de integração de CI), é melhor ter alguns arquivos no início.

Configurações do ReSharper

Se você é um desenvolvedor .NET profissional, provavelmente usa o ReSharper. O ReSharper é muito flexível no gerenciamento de suas configurações. Como líder de equipe, você pode criar e distribuir configurações compartilhadas em equipe que serão usadas por outros desenvolvedores. As configurações do Team Shared são armazenadas em um arquivo com extensão .DotSettings . O ReSharper selecionará essas configurações automaticamente se o nome do arquivo corresponder ao nome da solução do Visual Studio:

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

Portanto, você deve criar esse arquivo no início se quiser aplicar algumas configurações a toda a equipe. Um bom exemplo seria a regra de usar (ou não usar) a palavra-chave var . Seu arquivo de configurações compartilhado em equipe pode ter apenas essa regra, enquanto outras são a preferência dos desenvolvedores. Vale a pena mencionar que da mesma forma que as configurações do ReSharper podem ser definidas em um nível por projeto, porque você pode ter algum código legado que não pode modificar (por exemplo, alterar para usar a palavra-chave var ).

Se você nomeou esse arquivo corretamente, conforme mostrado no exemplo, qualquer nova instância do Visual Studio com uma nova configuração do ReSharper selecionará esse arquivo automaticamente e aplicará as regras. Não se esqueça de confirmar este arquivo no controle de origem.

Regras do StyleCop

Igual às configurações do ReSharper, você pode compartilhar as configurações do StyleCop. Se você usa o ReSharper, provavelmente está com o plug-in de integração instalado que aproveitará o StyleCop do ReSharper. No entanto, StyleCop armazena suas configurações independentemente em arquivos denominados Settings.StyleCop . Da mesma forma, você pode ter esse arquivo junto com o arquivo de solução e os arquivos de projeto.

Se você estiver usando o StyleCop, não se esqueça de executar a ferramenta de configuração do StyleCop e desativar as verificações que não deseja executar. Por padrão, todas as verificações estão habilitadas. Salve as novas configurações neste arquivo e confirme no controle de origem.

Arquivos de texto

Se você está construindo um produto público e vai publicar o código fonte, não se esqueça de criar e confirmar estes arquivos também:

 README.md LICENSE

Eu recomendo usar o formato markdown para o arquivo README.md , porque ele se tornou um padrão industrial e suportado por serviços públicos de controle de fonte como GitHub, bem como servidores internos como BitBucket (antigo Stash).

Especificações do NuGet

Se você estiver criando uma biblioteca que será distribuída na Galeria NuGet, provavelmente precisará criar arquivos de especificação de pacote, como MyProject.nuspec . Prefiro criar esses arquivos manualmente e enviá-los para o controle de origem. Os pacotes geralmente são lançados por um de seus trabalhos de Integração Contínua (CI para abreviar), mas também a qualquer momento você pode criar e publicar um pacote manualmente a partir do console da seguinte maneira:

 nuget.exe pack MyLibrary.nuspec

Só não esqueça de incrementar a versão do pacote antes de executar este comando.

Arquivos específicos de CI

Todos nós usamos servidores CI diferentes e todos eles têm scripts e configurações de configuração diferentes. Eu apenas mencionaria algumas das adições comuns que você pode considerar adicionar:

• Configurações NUnit , que especificam quais assemblies contêm testes a serem executados no servidor CI para trabalhos específicos. Todos os testes são praticamente divididos em algumas categorias. Existem testes de unidade que devem ser executados em cada compilação, testes de desempenho que são executados todas as noites e testes de integração são executados por versão.
• Configurações NCover , que especificam quais conjuntos de teste devem ser analisados ​​para cobertura de teste.
• As configurações do SonarQube , que determinam as métricas do software, serão coletadas.
• Scripts de trabalho , como NAnt, PowerShell ou simplesmente arquivos em lote do Windows.

Configurando projetos

Arquivos de projeto, ou seja, .csproj ou .vbpro , contêm todas as configurações usadas pelo Visual Studio e MSBuild. No entanto, nem todos estão disponíveis na janela Propriedades do Projeto. Para editar esses arquivos no Visual Studio manualmente, você deve fazer o seguinte:

• Clique com o botão direito do mouse em um projeto na visualização Solution Explorer.
• Selecione Descarregar Projeto .
• Clique com o botão direito do mouse novamente para escolher a ação Editar xyz.csproj .
• Edição completa.
• Clique com o botão direito do mouse no projeto novamente e escolha Reload Project .

Alternativamente, você pode abrir um arquivo de projeto em seu editor de texto favorito, editá-lo e salvá-lo. Ao voltar para a janela do Visual Studio, você será solicitado a recarregar o projeto alterado.

Controle de Avisos

Construir um software de alta qualidade requer que você nunca ignore os avisos de construção. Portanto, você deve habilitar o nível máximo de avisos e tratar todos os avisos como erros. Observe que você deve fazer isso para todas as configurações de compilação que tiver, como Debug e Release. A melhor maneira de fazer isso é gravar as seguintes configurações no grupo de propriedades comuns:

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

E certifique-se de não ter as mesmas configurações em outros grupos de propriedades. Caso contrário, eles substituirão as propriedades correspondentes do grupo comum.

FxCop

A execução do FxCop é meramente prática em todas as compilações. A maioria das equipes prefere executar o FxCop de tempos em tempos (geralmente antes de um lançamento) para garantir que não haja erros graves introduzidos. No entanto, se você deseja realizar a verificação final em cada compilação, adicione esta opção:

 <RunCodeAnalysis>true</RunCodeAnalysis>

Observe que FxCop, como StyleCop, tem suas próprias configurações que podem ser colocadas na pasta raiz e adicionadas ao controle de origem. Essas configurações provavelmente são usadas ao executar o FxCop em servidores CI.

Documentação

Esta parte é sobre XmlDoc. Se você estiver criando uma API pública, deverá criar e manter a documentação da API. A maioria dos desenvolvedores começa com o desenvolvimento de API (codificação real) e, pouco antes de um lançamento, eles habilitam a configuração do projeto Build / XML documentation file . Naturalmente, após outra reconstrução, vários erros aparecem, porque cada XmlDoc ausente está resultando em um erro de compilação. Para evitar isso, você deve habilitar a opção mencionada no início.

Se você tem preguiça de escrever uma documentação adequada ou não gosta de digitar muito texto, experimente instrumentos que automatizem esse processo, como o GhostDoc.

Contratos de código

Code Contracts é uma excelente estrutura da Microsoft Research, que permite expressar pré-condições, pós-condições e invariantes de objeto em seu código para verificação de tempo de execução, análise estática e documentação. Eu usei isso em muitos projetos críticos e ajudou muito, então eu encorajo você a tentar.

Se você decidir usar Contratos de código, é importante habilitar Contratos logo no início, quando você acabou de criar um novo projeto. A adição de contratos no meio do desenvolvimento é possível, mas exigirá alterações em muitas classes, para que os contatos correspondam uns aos outros. Portanto, não se esqueça de habilitar todas as configurações necessárias (pelo menos CodeContractsEnableRuntimeChecking ) e certifique-se de que essas configurações apareçam no grupo de propriedades comuns.

Aplicação do StyleCop

Anteriormente, falamos sobre a configuração do StyleCop para o tempo de desenvolvimento. No entanto, quando seu projeto é criado em um servidor CI, o ReSharper não tem efeito e, portanto, devemos habilitar a validação do StyleCop para execução com o MSBuild.

Isso geralmente é feito por modificação manual do arquivo de projeto. Você precisa descarregar o projeto no Visual Studio, editar o arquivo do projeto e carregar o projeto de volta:

 <PropertyGroup> <!— add this to the common property group (common to Debug/Release/etc) —> <StyleCopTreatErrorsAsWarnings>false</StyleCopTreatErrorsAsWarnings> </PropertyGroup> <!— add this Import in the very bottom —> <Import Project="$(ProgramFiles)\MSBuild\Microsoft\StyleCop\v4.3\Microsoft.StyleCop.targets">

A configuração StyleCopTreatErrorsAsWarnings fará o que diz: quebrará sua compilação em qualquer violação de regra StyleCop. O elemento de importação é necessário para que o MSBuild adicione a tarefa StyleCop à cadeia de compilação.

Você deve ter notado o caminho para Program Files . Como os desenvolvedores podem ter diferentes versões do StyleCop instaladas, algumas equipes preferem manter uma cópia privada da mesma instalação do StyleCop sob controle de origem. Neste caso, o caminho será relativo. Isso também facilita a configuração das máquinas CI, pois você não precisa instalar o StyleCop localmente.

Informações de montagem

Cada projeto .NET criado pelo assistente do Visual Studio terá o arquivo AssemblyInfo.cs preenchido automaticamente (consulte a subpasta Propriedades ) que contém alguns dos atributos do Assembly , mas nenhum assistente pode preencher todos os atributos do Assembly para você. Certifique-se de ter pelo menos estes atributos preenchidos:

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

Este mínimo é necessário para quaisquer assemblies que você vai distribuir. Um motivo prático por trás disso é o NuGet: se você estiver usando a criação automática de especificação do NuGet a partir do arquivo de assembly selecionado, essa ferramenta derivará as informações necessárias dessas propriedades.

Você também pode preencher mais uma propriedade no início:

 InternalsVisibleTo

Essa propriedade torna as classes e interfaces internas visíveis para o assembly especificado. Isso geralmente é usado para testes automatizados que você criará para seu projeto.

Cadeias de conexão

Como gerenciar strings de conexão é uma pergunta muito popular no Stack Overflow. O problema é como tornar as cadeias de conexão exclusivas para cada desenvolvedor ou trabalho de CI e não expor os detalhes da conexão ao publicar o código-fonte.

Em App.config (para aplicativos de desktop) ou Web.config (para aplicativos da web), faça a seguinte configuração que carregará o arquivo user.config em tempo de execução. Mantenha isso sob seu controle de origem:

 <?xml version="1.0" encoding="utf-8" ?> <configuration> <connectionStrings configSource="user.config"></connectionStrings> </configuration>

Aparentemente, o arquivo user.config deve ser excluído do controle de origem e todo desenvolvedor deve ter uma cópia local desse arquivo, preservando a privacidade da string de conexão:

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

.gitignore

Para quem usa o Git como controle de origem, é importante adicionar alguns padrões de arquivo ao arquivo .gitignore . No entanto, nossa comunidade inteligente já construiu um arquivo generalizado, que pode ser encontrado aqui: github.com/github/gitignore/blob/master/VisualStudio.gitignore.

Você deve tomá-lo como um arquivo .gitignore de referência e simplesmente adicionar suas exclusões personalizadas que você pode precisar.

Selos do GitHub

Você pode ter visto emblemas bonitos aparecendo na página do projeto README . Se você estiver publicando seu projeto no GitHub, considere conectar seu projeto a serviços públicos para:

• Construção: para mostrar que uma construção está falhando ou passando.
• Teste: para mostrar a cobertura do teste e o status de execução do teste.
• Publicação: para mostrar a versão mais recente do pacote NuGet.

Uma lista completa de emblemas e serviços relacionados pode ser encontrada em shields.io. Você pode encontrar muitos emblemas interessantes que são bons para projetos de código aberto.

Depois de registrar seu projeto com um serviço selecionado, você receberá um link para a imagem e um link de sintaxe de remarcação completo, que pode ser adicionado ao seu arquivo README.md . A propósito, essa é uma das razões pelas quais você deve preferir markdown para arquivos Leiame .

Exemplos de emblemas de remarcação, do projeto Roslyn:

[![Build Status]([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/)) [![Join the chat at [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))

Validação Automática da Estrutura da Solução

Mesmo que você tenha definido todas as configurações discutidas neste artigo, mais cedo ou mais tarde um de seus desenvolvedores poderá alterá-las e confirmar as alterações no controle de origem. Às vezes, isso acontece por engano e, muitas vezes, essas alterações não são detectadas durante a revisão do código. Além desses acidentes, devemos estar atentos aos seguintes erros comuns:

• Referências inválidas : quando alguém está referenciando um assembly local que outros talvez não tenham, ou quando alguém excluiu um arquivo do disco, enquanto o link para esse arquivo permanece no arquivo .csproj . Isso certamente quebrará a compilação, mas pode acontecer tarde demais quando a alteração for enviada e outros a retiraram. Isso é especialmente crucial para arquivos da Web estáticos, que você não pode verificar durante a compilação.
• Consistência de nomenclatura : as ferramentas como StyleCop podem controlar o código-fonte C#, mas nenhuma ferramenta pode impor regras para arquivos de projeto ou propriedades de montagem. Um bom exemplo é este: Queremos nomear projetos para corresponder ao nome do assembly de saída e queremos que os nomes dos projetos tenham um prefixo comum como MyCompany.MyProduct .

Descobri que observar esses erros nas revisões de código é propenso a erros e deve ser automatizado. Então escrevi uma ferramenta simples que realiza essas e muitas outras verificações para verificar a consistência da solução. Conheça o SolutionInspector. Este é Open Source e distribuído sob licença do MIT. Você pode compilá-lo a partir do código-fonte ou instalar do NuGet:

 Install-Package SolutionInspector

A ferramenta percorre toda a estrutura da solução e aplica muitas regras de validação. As regras são configuradas por arquivos XML, colocados junto com outros arquivos de solução. Para controlar as configurações por projeto, basta adicionar o mesmo arquivo com configurações diferentes à pasta do projeto correspondente.

Nenhum arquivo de configuração é necessário por padrão. Nesse caso, a ferramenta aplicará todas as regras disponíveis e enviará todos os problemas para o console.

Aqui está o exemplo do arquivo de configuração:

 <?xml version="1.0" encoding="utf-8"?> <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>

Embora as configurações sejam bastante descritivas, vou explicar algumas delas:

• MinSolutionFormatVersion / MaxSolutionFormatVersion impedirá que seus desenvolvedores alternem a versão do Visual Studio.
• DetectMissingFiles é muito útil para conteúdo da Web estático ou outros arquivos não codificados adicionados à solução ou a um projeto.
• AllowBuildEvents pode impedir a adição de eventos de compilação personalizados, que podem fazer coisas desnecessárias.
• Properties é o elemento mais flexível: você pode verificar quaisquer propriedades em relação aos valores desejados, sejam propriedades conhecidas ou personalizadas.

Conclusão

Revisamos várias práticas padrão, arquivos de configuração e configurações de projeto que você pode aplicar ao iniciar um novo projeto. Fazer isso logo no início diminuiria a dívida técnica futura e tornaria o código-fonte do seu produto bonito e profissional. Para projetos de código aberto, isso é de particular importância, porque qualquer colaborador conheceria suas expectativas examinando as configurações da solução e os arquivos do projeto.