Guia de instalação detalhado

Depois de ter acesso ao código (em codespaces ou localmente) seguindo o guia de Introdução, siga estas etapas:

Etapa 1: Executar o script de instalação

O script de instalação automatiza a maior parte da configuração (registro de aplicativo, padrões etc.).

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

Notas de script de instalação:

• WorkloadName deve seguir o padrão Organization.WorkloadName. Para desenvolvimento, use Org.[YourWorkloadName].
• Se você estiver reutilizando um aplicativo existente do Microsoft Entra, verifique se as URIs de redirecionamento do SPA estão configuradas conforme descrito no guia de instalação manual de repositórios.
• Em macOS/Linux, use pwsh para executar scripts.
• Verifique se a política de execução do PowerShell está definida como Irrestrita e os arquivos serão desbloqueados se você for perguntado se os arquivos do PowerShell devem ser iniciados.
• Siga as diretrizes que o Script fornece para obter a configuração de tudo

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

Etapa 2: Iniciar o ambiente de desenvolvimento

Execute o servidor de desenvolvimento (front-end + APIs) e registre sua instância local com o 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

Etapa 3: Habilitar recursos do desenvolvedor no Fabric

Navegue até o portal do Fabric e defina as configurações necessárias:

3.1 Configurar as configurações de 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:

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

3.2 Ativar o Modo de Desenvolvedor do Fabric:

Navegue até as Configurações do Desenvolvedor do Fabric e habilite o Modo de Desenvolvedor do Fabric:

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

Etapa 4: Testar o item HelloWorld

Você pode acessar o processo a partir do Hub de Tarefas (procure o nome do seu processo) ou acessar diretamente a página. Em seguida, crie um item Hello World.

Steps:

1. Hub de Carga de Trabalho do Open Fabric: localize 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 carga de trabalho (por exemplo, Org.MyWorkload)

2. Crie um novo item: selecione o tipo de item Hello World e escolha seu workspace de desenvolvimento.

3. Verificar a funcionalidade: o editor é aberto; confirme se o item funciona conforme o esperado e aparece como um artefato nativo no workspace.

Parabéns! Você criou seu primeiro item a partir do seu ambiente de desenvolvimento.

Etapa 5: Iniciar codificação

Agora que você está tudo configurado, você pode começar a criar seus próprios itens personalizados. Siga nosso guia abrangente para saber como criar itens personalizados do Fabric:

📖 Criando o Guia de Itens de Malha Personalizado – Este guia fornece duas abordagens para a criação de itens:

• Abordagem com Assistência de IA: Usar o GitHub Copilot para orientação interativa (recomendado para novos desenvolvedores)
• Abordagem manual com script: use scripts automatizados do PowerShell para configuração rápida (recomendado para desenvolvedores experientes)

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

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

Boa programação! 🚀

Práticas recomendadas

• Bifurque o repositório: bifurque o repositório Starter-Kit e use sua bifurcação como base do seu projeto.
• Mantenha em sincronia: mantenha seu fork em sincronia com o upstream para obter melhorias.
• Manter a consistência da estrutura do projeto: preservar a estrutura do projeto do Starter-Kit e os padrões de organização para garantir a compatibilidade com atualizações futuras e manter a clareza do código.
• Integração regular Starter-Kit: integre regularmente as alterações de código do Starter-Kit ao projeto para se beneficiar de correções de bugs, novos recursos e atualizações de segurança. Configure um processo para revisar e mesclar alterações upstream regularmente (mensal ou trimestral).
• Valide os manifestos antecipadamente: valide o manifesto da carga de trabalho antecipadamente e siga as permissões de privilégio mínimo.
• Usar contêineres de desenvolvimento: use um contêiner de desenvolvimento ou codespaces para um ambiente consistente e descartável.
• Use scripts fornecidos: use os scripts fornecidos (Setup, StartDevServer, StartDevGateway) para automatizar a instalação e o fluxo de trabalho diário.

Solução de problemas comuns

Erro de instalação do PowerShell

Se você encontrar um erro durante a execução do script de instalação, verifique se você tem o PowerShell mais recente instalado e configurado no ambiente em que você executa o script.

Erro de política de execução de script

Se você encontrar: 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 puder iniciar na porta 5173, localize e encerre 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 você encontrar erros referentes à falta de dependências:

# From Workload folder
cd Workload
npm install

Problemas de autenticação do DevGateway

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

1. Verificar as URIs de redirecionamento de registro do aplicativo no Microsoft Entra
2. Verifique se as configurações de locatário permitem os recursos de desenvolvedor necessários
3. Verifique se você está conectado ao locatário correto no DevGateway

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

Notas importantes

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

O Google introduziu novas restrições de Acesso à Rede Local (LNA) no Chrome que interromperão o desenvolvimento local com o DevServer. Essas restrições impedem que os sites acessem recursos de rede local sem permissão explícita do usuário.

Ação necessária para o desenvolvimento local: você deve alterar sua configuração do Chrome para continuar desenvolvendo cargas de trabalho localmente:

1. Navegue até chrome://flags/#local-network-access-check no Chrome
2. Definir o sinalizador como "Desabilitado"
3. Reiniciar o Chrome

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

Recursos adicionais:

• Acesso à Rede Local – Desenvolvedores do Chrome – Documentação oficial do Chrome sobre alterações no Acesso à Rede Local

Próximas etapas

• Conheça a arquitetura e como o host, seu aplicativo e os serviços do Fabric interagem
• Ler a visão geral do manifesto para o esquema e as práticas recomendadas
• Entender a estrutura e a configuração do manifesto da carga de trabalho
• Desenvolver com o DevGateway para testes locais
• Publique seu trabalho quando estiver pronto para compartilhá-lo largamente