Extensibilidade — visão geral

Extensibilidade é um requisito central do Pipevine, não um recurso adicional. Esta página define cada ponto de extensão e o contrato que um pacote de terceiro precisa cumprir para adicionar vocabulário próprio ao YAML — sem fork do framework.

Princípio de desenho

Nenhum recurso do framework é implementado de um jeito que só o próprio Pipevine consiga replicar.

Se um step embutido precisa de algum gancho especial, esse gancho é parte da API pública — qualquer pacote de terceiro tem acesso exatamente ao mesmo mecanismo. Um step, provider de banco, broker, provider de cache ou esquema de autenticação escrito fora do repositório do Pipevine, consumindo apenas os pacotes NuGet publicados, tem o mesmo poder que um equivalente embutido.

Como uma extensão é ativada

Três passos, sempre os mesmos, para qualquer ponto de extensão:

  1. O consumidor referencia o pacote (<PackageReference Include="Acme.Pipevine.Mongo" />).
  2. O pacote registra suas implementações no DI, tipicamente via um método de extensão que o próprio pacote expõe (services.AddPipevineMongo()).
  3. O YAML passa a poder usar a chave (provider: mongodb, type: acme.enrich, scheme: hmac, conforme o ponto de extensão).

A resolução em runtime é por DI keyed services, com a chave sendo exatamente a string usada no YAML — não existe um registro central de "plugins conhecidos" para atualizar.

Se a chave aparece no YAML mas nenhuma implementação foi registrada, o erro é claro e aponta para a linha/coluna do documento:

orders.pipevine.yaml(14,20): error PV3010: nenhum provider de dados registrado
para a chave 'mongodb'. Referencie o pacote que a fornece.

Os pontos de extensão

Interface O que adiciona Chave no YAML
IStep Um novo passo de pipeline type:
IDataProvider Um novo banco de dados provider: (em dataSources)
IBrokerProvider Um novo broker de mensageria provider: (em brokers)
ICacheProvider Um novo backend de cache provider: (em caches)
IInboundAuthScheme Um novo esquema de autenticação de entrada scheme: (em auth.schemes)
IOutboundAuthProvider Autenticação para integrações de saída scheme: (em integrations[].auth)
IExpressionEngine Uma linguagem de expressão nova, ou funções adicionais na JSONata existente engine: (default jsonata)
IStepCodeEmitter Caminho rápido opcional de compile-time para um step existente (acompanha o IStep correspondente)
ISecretResolver Uma nova fonte de segredos ${<chave>:...}

Cada guia parte de um exemplo mínimo funcional, não de uma descrição abstrata da interface.

Estabilidade da API pública

  • Toda superfície pública dos pacotes de abstração (Pipevine.Abstractions, Pipevine.Data.Abstractions, Pipevine.Caching.Abstractions, e assim por diante) é rastreada explicitamente — qualquer adição é uma mudança revisável, nunca silenciosa.
  • SemVer estrito: quebra de contrato só acontece em uma versão major. Veja Versionamento para a política completa.
  • Novos membros em interfaces são adicionados como default interface members sempre que possível, para não quebrar implementações de terceiro já existentes.

Diagnósticos para autores de extensão

Um analisador Roslyn dedicado emite a faixa PV4xxx para quem está escrevendo uma extensão — referencie-o (com PrivateAssets="all") no .csproj do seu pacote de extensão:

Código Situação
PV4001 Implementação de IStep sem o atributo [Step]
PV4002 Campo mutável em uma implementação de IStep — quebra a garantia de thread-safety
PV4010 IStepFactory sem schema de configuração declarado — impede validação do YAML no formato de schema (aviso, não bloqueia)
PV4020 Chave de step colidindo com uma chave já registrada

Para onde ir daqui

Escolha o ponto de extensão que sua extensão precisa e siga o guia correspondente — cada um começa com um exemplo completo e funcional:

Edit this page