Partilhar via

Guia Detalhado de Configuração

Assim que tiver acesso ao código (seja em Codespaces ou localmente) seguindo o guia Getting Started, siga estes passos:

Sugestão

Se não quiseres seguir os passos manualmente, pede ao GitHub Copilot para te ajudar a fazer o trabalho. O repositório Starter-Kit é compatível com IA e o Copilot pode guiá-lo interativamente durante o processo de configuração. Experimenta este prompt: "Ajuda-me a começar com este repositório e a executar o sample do HelloWorld."

Passo 1: Execute o script de configuração

O script de configuração automatiza a maioria das configurações (registro de aplicativos, padrões, etc.).

# From the repo root
pwsh ./scripts/Setup/Setup.ps1 -WorkloadName "Org.MyWorkload"

Notas do script de preparação:

  • WorkloadName deve seguir o padrão Organization.WorkloadName. Para o desenvolvimento, use Org.[YourWorkloadName].
  • Se estiver reutilizando um aplicativo existente do Microsoft Entra, verifique se os URIs de redirecionamento do SPA estão configurados conforme descrito no guia de configuração manual de repositórios.
  • Em macOS/Linux, use pwsh para executar scripts.
  • Certifique-se de que a política de execução do PowerShell está definida como Irrestrito e que os arquivos são desbloqueados se você estiver sendo perguntado se os arquivos do PowerShell devem ser iniciados.
  • Siga as orientações fornecidas pelo Script para configurar tudo

O script de instalação pode ser executado várias vezes. Se os valores já estiverem presentes, você será perguntado se eles devem ser substituídos. Se você quiser substituir tudo, use o parâmetro Force.

Observação

Se encontrar erros de configuração, consulte o erro de configuração do PowerShell na secção de resolução de problemas abaixo.

Sugestão

Se tiveres problemas com o script de configuração automatizado, podes seguir o Manual Setup Guide para uma configuração manual passo a passo.

Passo 2: Iniciar o ambiente de desenvolvimento

Execute o servidor de desenvolvimento (front-end + APIs) e registre sua instância local no Fabric via DevGateway.

# Terminal 1: start local dev server
pwsh ./scripts/Run/StartDevServer.ps1

# Terminal 2: start DevGateway to register your local instance with Fabric
pwsh ./scripts/Run/StartDevGateway.ps1

Passo 3: Ativar funcionalidades de programador no Fabric

Navegue até ao portal do Fabric e configure as definições necessárias:

3.1 Configurar as definições do inquilino no Portal de Administração:

Vá para as configurações do Portal de Administração e habilite as seguintes configurações de locatário:

  • Os administradores e colaboradores de capacidade podem adicionar e remover cargas de trabalho adicionais
  • Os administradores do espaço de trabalho podem desenvolver cargas de trabalho de parceiros
  • Os usuários podem ver e trabalhar com cargas de trabalho adicionais não validadas pela Microsoft

Captura de ecrã das definições do locatário.

3.2 Ativar o Modo de Desenvolvimento Fabric:

Navegue até às Definições de Desenvolvedor do Fabric e ative o Modo de Desenvolvedor do Fabric:

Captura de ecrã do modo desenvolvedor do Fabric.

Agora está pronto para criar o seu primeiro Item Hello World no Fabric.

Passo 4: Testa o item HelloWorld

Você pode acessar a carga de trabalho a partir do Hub de Carga de Trabalho (procure o nome da carga de trabalho) ou navegar diretamente. Em seguida, crie um item Hello World.

Steps:

  1. Open Fabric Workload Hub: Localize a sua carga de trabalho (por exemplo, Org.MyWorkload).

    • Navegação direta: https://app.fabric.microsoft.com/workloadhub/detail/<WORKLOAD_NAME>?experience=fabric-developer
    • Substitua <WORKLOAD_NAME> pelo nome real da sua carga de trabalho (por exemplo, Org.MyWorkload)

  2. Crie um novo item: Selecione o tipo de item Hello World e escolha o seu espaço de trabalho de desenvolvimento.

  3. Verificar funcionalidade: O editor abre; Confirma que o item funciona como esperado e parece um artefacto nativo no espaço de trabalho.

Parabéns! Criaste o teu primeiro item a partir do teu ambiente de desenvolvimento.

Passo 5: Começar a programar

Agora que está tudo configurado, pode começar a criar os seus próprios itens personalizados. Siga o nosso guia completo para aprender a criar peças personalizadas em Tecido:

📖 Guia de Criação de Itens de Tecido Personalizados - Este guia apresenta duas abordagens para criar itens:

  • Abordagem Assistida por IA: Use o GitHub Copilot para orientação interativa (recomendado para novos programadores)
  • Abordagem Manual Scriptada: Utilize scripts automatizados PowerShell para uma configuração rápida (recomendado para programadores experientes)

Opções de início rápido:

  • Atualize o editor existente do HelloWorld: Workload/app/items/HelloWorldItem/HelloWorldItemEditor.tsx
  • Estruture um novo item com o script: ./scripts/Setup/CreateNewItem.ps1

Feliz codificação! 🚀

Melhores práticas

  • Faça um fork do repositório: Faça um fork do repositório Starter-Kit e use o seu fork como base do seu projeto.
  • Mantenha-se sincronizado: Mantenha o seu fork sincronizado com o upstream para captar melhorias.
  • Manter a consistência da estrutura do projeto: Preservar a estrutura do projeto e os padrões organizacionais do Kit de Início para garantir a compatibilidade com futuras atualizações e manter a clareza do código.
  • Integração Starter-Kit regular: Integre regularmente alterações de código do Starter-Kit no seu projeto para beneficiar de correções de bugs, novas funcionalidades e atualizações de segurança. Estabeleça um processo para rever e fundir modificações de upstream regularmente (mensal ou trimestralmente).
  • Valide os manifestos antecipadamente: Valide o seu manifesto de carga de trabalho cedo e siga as permissões de privilégio mínimo.
  • Utilizar contentores de desenvolvimento: Utilize um contentor de desenvolvimento ou Codespaces para um ambiente consistente e descartável.
  • Use os scripts fornecidos: Use os scripts fornecidos (Setup, StartDevServer, StartDevGateway) para automatizar a configuração e o fluxo de trabalho diário.

Solução de problemas comuns

Erro de configuração do PowerShell

Se encontrar um erro durante a execução do script de configuração, certifique-se de que tem o PowerShell mais recente instalado e configurado no ambiente onde executa o script.

Captura de tela do erro de configuração do PowerShell.

Erro na política de execução de scripts

Se encontrar o seguinte: cannot be loaded because the execution policy is unrestricted

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

A porta 5173 está em uso

Se o DevServer não conseguir iniciar na porta 5173, encontre e termine o processo:

# Find process using port
Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess

# Terminate process
Stop-Process -Id <ProcessId> -Force

Erros de dependências

Se encontrar erros relacionados a dependências ausentes:

# From Workload folder
cd Workload
npm install

Problemas de autenticação DevGateway

Se a autenticação falhar ao iniciar o DevGateway:

  1. Verifique os URIs de redirecionamento de registo de aplicações no Microsoft Entra
  2. Verifique se as definições de ambiente permitem as funcionalidades de desenvolvimento necessárias.
  3. Certifique-se de que já iniciou sessão no tenant correto no DevGateway

Para informações completas sobre resolução de problemas, consulte o Starter-Kit Repository README.

Observações importantes

Novas restrições de acesso à rede local do Chrome

A Google introduziu novas restrições de Acesso à Rede Local (LNA) no Chrome que irão interromper o desenvolvimento local com o DevServer. Estas restrições impedem os websites de aceder aos recursos da rede local sem permissão explícita do utilizador.

Ação Necessária para o Desenvolvimento Local: Deve alterar a sua configuração do Chrome para continuar a desenvolver cargas de trabalho localmente:

  1. Navegar para chrome://flags/#local-network-access-check no Chrome
  2. Defina a bandeira para "Desativado"
  3. Reiniciar o Chrome

Por que isto é necessário: As novas restrições bloqueiam a comunicação entre a sua carga de trabalho a correr no Fabric e o servidor DevGateway local, o que é essencial para o fluxo de trabalho de desenvolvimento.

Recursos Adicionais:

Importante

Sem desativar esta bandeira, o desenvolvimento local com o DevGateway não funcionará no Chrome. Esta alteração de configuração é necessária apenas para ambientes de desenvolvimento.

Próximos passos

  • Last updated on