Analisadores Roslyn e Geradores de Código Fonte

Use este fluxo de trabalho ao adicionar ou alterar um analisador Roslyn, correção de código, gerador de código fonte, testes, dependências ou layout de pacote. Primeiro, inspecione os frameworks de destino do repositório, o gerenciamento central de pacotes, o framework de teste, as convenções de analisadores e geradores, a alocação de IDs de diagnóstico, a localização e a embalagem. Preserve as convenções estabelecidas, a menos que elas entrem em conflito com as regras de compatibilidade abaixo.

Regras de design inegociáveis

• Prefira a análise baseada em IOperation sempre que possível. Registre o OperationKind mais restrito aplicável e inspecione operações tipadas como IInvocationOperation, IAwaitOperation ou IObjectCreationOperation. Isso geralmente suporta C# e VB com um analisador e fornece acesso direto a símbolos e conversões.
• Use análise de sintaxe apenas para regras inerentemente sintáticas ou sintaxe não representada adequadamente por IOperation. Um callback de nó de sintaxe já possui um SemanticModel; não chame Compilation.GetSemanticModel ou obtenha outro modelo semântico dele. A criação repetida de modelos semânticos é cara e muitas vezes indica que uma ação de operação ou símbolo é a melhor abstração.
• Todo analisador deve suportar C#. O suporte a VB.NET é opcional até ser solicitado ou o precedente estabelecido no repositório exigir. Um analisador de operação independente de linguagem pode declarar ambas as linguagens. Se o suporte a VB for prometido, inclua trechos equivalentes em C# e VB nos testes; não infira a correção do VB apenas pela implementação compartilhada.
• Mantenha os provedores de analisadores e correções de código em assemblies distintos. O projeto do analisador nunca deve referenciar pacotes Roslyn Workspaces. Dependências de Workspaces pertencem apenas aos projetos de correção de código e teste.
• Callbacks de analisadores devem ser sem estado ou seguros para concorrência. Chame EnableConcurrentExecution(). Faça uma escolha explícita de código gerado com ConfigureGeneratedCodeAnalysis(...); siga a política do repositório em vez de aceitar silenciosamente o padrão.
• Respeite o cancelamento onde as APIs expõem um token. Não retenha compilações, operações, árvores de sintaxe, símbolos ou modelos semânticos em estado estático.
• Evite InternalsVisibleTo. Teste analisadores por meio de suas APIs públicas DiagnosticAnalyzer e CodeFixProvider e do harness de teste do Roslyn. Um pequeno auxiliar de analisador pode ser público quando o teste direto é genuinamente útil, mas a maior parte do comportamento deve ser testada de ponta a ponta.
• Centralize nomes de metadados e nomes de membros em vez de propagar strings mágicas. Use um catálogo estático compartilhado para nomes de tipos totalmente qualificados, namespaces e nomes de membros de API.
• Nunca identifique um símbolo, incluindo uma classe de atributo, chamando ToDisplayString() e comparando o resultado com um literal de string. Resolva um tipo nomeado esperado do Compilation uma vez por nome de metadado. Para resolver um método, propriedade, campo ou evento, primeiro resolva seu tipo contêiner, depois selecione o membro esperado por nome e assinatura. Compare os símbolos encontrados com SymbolEqualityComparer.Default.Equals(actual, expected). Quando as substituições genéricas forem irrelevantes, compare tipos nomeados, propriedades, campos e eventos por OriginalDefinition; compare métodos após substituir um método de extensão reduzido por ReducedFrom ?? method e, em seguida, obter OriginalDefinition. Normalize os símbolos esperados e encontrados, e inspecione os argumentos de tipo separadamente quando eles fazem parte da correspondência. Strings de exibição são para apresentação, não para identidade, e podem variar com formatação, aliases, qualificação, nulidade e outro contexto.
• Documente cada ID de diagnóstico. Quando o repositório usa Docfx, coloque a documentação do analisador sob sua árvore Docfx, tipicamente docfx/analyzers, e inclua cada página na tabela de conteúdo relevante.
• Defina a versão de cada assembly de analisador com precisão suficiente para que cada commit produza uma versão de assembly única. Ao usar Nerdbank.GitVersioning, dê a cada projeto de analisador seu próprio version.json com assemblyVersion.precision definido como revision e garanta que as propriedades MSBuild de todo o repositório não impeçam que esse arquivo seja descoberto.
• Geradores de código fonte devem implementar IIncrementalGenerator, não ISourceGenerator. Projete o grafo do provedor para que as entradas inalteradas permaneçam em cache e não regenerem a saída.
• Geradores de código fonte devem usar uma pequena abstração SourceWriter para novas linhas determinísticas, indentação, codificação e saída balanceada. Comece em SourceWriter.cs e adapte seu namespace e detalhes de framework de destino ao repositório receptor.

…