Compartilhar via

Configurando o Electron para desenvolvimento de API do Windows

Este guia orienta você na configuração do ambiente de desenvolvimento do Electron para o desenvolvimento da API do Windows. Você instalará as ferramentas necessárias, inicializará o project e configurará os SDKs do Windows.

Ao final deste guia, você terá um aplicativo Electron que:

  • Chama as APIs modernas do Windows (Windows SDK e Windows App SDK)
  • Pode usar complementos nativos com funcionalidades de IA (Phi Silica ou WinML)
  • É executado com a identidade do aplicativo para testar APIs protegidas
  • Pode ser empacotado como um MSIX assinado para distribuição

Pré-requisitos

  • Windows 11 (Pc Copilot+ se estiver usando Phi Silica)
  • Node.js - winget install OpenJS.NodeJS --source winget
  • .NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
  • Visual Studio com a Carga de Trabalho de Área de Trabalho Nativa - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

Etapa 1: Criar um novo aplicativo Electron

Comece com um novo aplicativo Electron usando Electron Forge. Se você tiver um aplicativo existente, ignore esta etapa.

npm create electron-app@latest my-windows-app
cd my-windows-app

Verifique se o aplicativo é executado:

npm start

Etapa 2: Instalar a CLI do winapp

npm install --save-dev @microsoft/winappcli

Etapa 3: inicializar o projeto para desenvolvimento do Windows

npx winapp init

Quando solicitado:

  • Nome do pacote: Pressione Enter para aceitar o padrão (my-windows-app)
  • Nome do publicador: pressione Enter para aceitar o valor padrão ou insira seu nome
  • Versão: Pressione Enter para aceitar 1.0.0.0
  • Ponto de entrada: pressione Enter para aceitar o padrão (my-windows-app.exe)
  • SDKs de instalação: selecione "SDKs estáveis"

O que faz winapp init ?

Este comando configura tudo o que você precisa para o desenvolvimento do Windows:

  1. Cria pasta contendo cabeçalhos e bibliotecas do SDK do Windows e Windows App SDK
  2. Gera appxmanifest.xml - O manifesto do aplicativo necessário para a identidade do aplicativo e o empacotamento MSIX
  3. Cria Assets/ pasta – Contém ícones de aplicativo e ativos visuais
  4. Cria winapp.yaml – rastreia versões do SDK e configuração do projeto
  5. Instala Windows App SDK runtime – componentes de runtime necessários para APIs modernas
  6. Habilita o modo de desenvolvedor no Windows – Necessário para depuração

Observação

A pasta .winapp/ é adicionada automaticamente a .gitignore e não deve ser enviada para o controle de versão.

Etapa 4: Adicionar restauração ao pipeline de build

Adicione um script postinstall ao seu package.json para garantir que os SDKs do Windows estejam disponíveis quando outros desenvolvedores clonarem seu projeto.

{
  "scripts": {
    "postinstall": "winapp restore && winapp node add-electron-debug-identity"
  }
}

Esse script é executado após npm install e:

  1. winapp restore – Baixa e restaura todos os pacotes do SDK do Windows
  2. winapp node add-electron-debug-identity – Registra seu aplicativo Electron com a identidade de debug

Para projetos multiplataforma, crie scripts/postinstall.js:

if (process.platform === 'win32') {
  const { execSync } = require('child_process');
  try {
    execSync('npx winapp restore && npx winapp cert generate --if-exists skip && npx winapp node add-electron-debug-identity', {
      stdio: 'inherit'
    });
  } catch (error) {
    console.warn('Warning: Windows-specific setup failed.');
  }
} else {
  console.log('Skipping Windows-specific setup on non-Windows platform.');
}

Em seguida, atualize package.json:

{
  "scripts": {
    "postinstall": "node scripts/postinstall.js"
  }
}

Etapa 5: Noções básicas sobre a identidade de depuração

O comando winapp node add-electron-debug-identity:

  1. Lê o seu appxmanifest.xml para obter detalhes e funcionalidades do aplicativo
  2. Registra electron.exe em sua node_modules com uma identidade temporária
  3. Permite testar APIs necessárias para identidade sem criar um pacote MSIX completo

Execute este comando manualmente sempre que você modificar appxmanifest.xml ou vincular ativos:

npx winapp node add-electron-debug-identity

Teste sua configuração:

npm start

Observação

Há um bug conhecido no Windows associado a aplicativos Electron com embalagem esparsa, que pode resultar em falhas ou janelas em branco. Adicione --no-sandbox ao script inicial como uma solução alternativa: "start": "electron-forge start -- --no-sandbox". Esse problema não afeta o empacotamento MSIX completo. Para desfazer a identidade de depuração, execute npx winapp node clear-electron-debug-identity.

Próximas Etapas 

Agora que seu ambiente de desenvolvimento está configurado, crie complementos nativos e chame APIs do Windows:

  • Last updated on