path-types

Tipos de Caminho

Aplique estas orientações ao definir novos tipos. Altere o código existente apenas quando solicitado explicitamente e mantenha as edições mínimas e proporcionais. Trate essas regras como o estado alvo de uma migração em andamento; se a conformidade for difícil, pergunte ao usuário como proceder.

• Nos tipos de protocolo do servidor de aplicativos, use LegacyAppPathString para compatibilidade com versões anteriores durante a migração de URI. Na fronteira do protocolo, converta-o em PathUri e use PathUri internamente. Para lógica local ao host, como alguns valores de configuração, use AbsolutePathBuf ou PathBuf.
• Nos tipos de protocolo do servidor de execução, use PathUri. Internamente, use PathUri ou AbsolutePathBuf conforme apropriado.
• Em dependências compartilhadas por ambos os servidores, use PathUri ou APIs separadas que desacoplem seus casos de uso.
• Argumentos de chamada de ferramenta que se espera que o modelo gere devem ser desserializados como Strings regulares com código de manipulação de caminho específico do recurso.

Requisitos de Migração

Mantenha estes requisitos em mente ao migrar código para estar em conformidade com as diretrizes acima:

• clientes existentes do servidor de aplicativos continuam enviando e recebendo strings de caminho nativo herdadas
• o servidor de aplicativos pode reter e manipular URIs de caminho de plataforma estrangeira
• as APIs do servidor de execução usam URIs file://
• a operação apenas local não deve alterar o texto visível pelo modelo
• os argumentos de ferramenta do modelo podem conter caminhos relativos ou absolutos brutos para qualquer SO
• o raciocínio sobre caminhos deve funcionar antes de o ambiente relacionado estar online
• URIs não podem codificar explicitamente a convenção de caminho ou o sistema operacional do executor
• os usuários não devem configurar explicitamente a convenção de SO/caminho do ambiente
• URIs ainda não devem ser armazenados em rollouts, bancos de dados ou outro armazenamento persistente
• erros de conversão de caminho: falha fechada para caminhos relevantes à segurança, falha aberta para UI/diagnósticos
• prefira métodos pequenos e focados em PathUri ou LegacyAppPathString em vez de auxiliares locais
• represente valores PathUri como URIs em diagnósticos

É aceitável se a conversão entre caminhos e URIs for um tanto imprecisa, desde que funcione corretamente para usuários reais.

Migrar para URIs não deve adicionar novos modos de falha significativos. Precisaremos expor erros em alguns lugares que antes eram infalíveis, mas isso deve ser mantido ao mínimo.