Modelos de Projeto

O PowerPortalsPro traz dois modelos de projeto que estruturam um portal completo — conectividade, autenticação, manipuladores de segurança, localização e páginas de identidade pré-construídas — prontos para rodar em minutos. Um aplicativo React de página única (recomendado) e um aplicativo web Blazor estão ambos disponíveis, e o conjunto de recursos PowerPortalsPro é idêntico em ambos. Escolha a stack de front-end que se encaixe no seu time.

Instalação dos Templates

Instale o pacote PowerPortalsPro.AspNetCore.Templates do NuGet usando a CLI .NET. Ambos os templates vêm neste único pacote:

Escolhendo um Modelo

Uma vez instalado, crie um projeto a partir da CLI .NET ou do diálogo "Novo Projeto" do Visual Studio (procure por "Power Portals Pro"). Dois modelos estão disponíveis — escolha aquele que combina com sua pilha front-end:

React (recomendado)

Um host ASP.NET Core combinado com um aplicativo de página única React + Vite + TypeScript construído no Fluent UI React. Recomendado para novos portais — ferramentas modernas de front-end, um ciclo de desenvolvimento rápido com recarga a quente e o conjunto de componentes mais amplo.

Blazor

Um aplicativo web ASP.NET Core Blazor construído sobre o Fluent UI Blazor, com um modo de renderização que você escolhe no momento do andaime via --interactivity. É um ótimo encaixe quando sua equipe trabalha principalmente em C# e prefere ficar totalmente na pilha de interface do .NET.

Recomendado

Ambos os templates expõem as mesmas capacidades do PowerPortalsPro — grades, editores, segurança, localização e identidade. Sugerimos o React para novos projetos, a menos que sua equipe tenha um motivo específico para permanecer totalmente em C#, caso em que o template do Blazor é totalmente suportado.

O Modelo React

O powerportalspro-react template gera dois projetos que rodam juntos:

• ASP.NET Host Core — atende os dados e endpoints de autenticação do framework sob /api/* e hospeda o SPA construído. Ele Program.cs é configurado de forma semelhante ao host Blazor (conexão Dataverse, localização, handlers de segurança) e expõe os endpoints de autenticação JSON via MapAuthEndpoints<PortalUser>().
• Cliente React (.Client) — um SPA Vite + TypeScript construído sobre o Fluent UI React, que consume os @powerportalspro/corepacotes , @powerportalspro/react, @powerportalspro/react-fluent, e @powerportalspro/react-charts pacotes para a camada de transporte, ganchos e componentes.
• Dev loop — pressione F5 (ou execute dotnet run) no host e o SpaProxy inicia o servidor de desenvolvimento Vite para você, com recarregamento do módulo quente nas edições do cliente. Não é necessário um terminal separado.
• Mesma superfície do Blazor — páginas de exemplos de Contas/Contatos, páginas de identidade e gerenciamento de contas, manipuladores de permissões de tabelas, navegação e configurações de tema/site, tudo reconstruído com componentes React.

Modos de Interatividade Blazor

O template Blazor também aceita --interactivity Server, --interactivity WebAssembly, ou --interactivity Auto escolher seu modo de renderização (o template React é sempre um aplicativo de página única, então não tem opção equivalente). Escolher um modo logo de cara só afeta o layout do projeto gerado — o próprio PowerPortalsPro roda corretamente nos três. Veja a página Blazor Interactivity para uma comparação completa.

• Servidor — páginas interativas executadas no servidor por meio de uma conexão SignalR. A implantação mais simples e o menor download do cliente. Bom padrão quando você está em dúvida.
• WebAssembly — páginas interativas executadas no navegador como código compilado .NET. Estrutura um projeto separado .Client ; o servidor hospeda os endpoints da API consumidos pelo cliente. Ideal para UX rico do lado do cliente e trabalho de interação descarregado do servidor.
• Auto — renderiza a primeira pintura no servidor para uma carga rápida e percebida, depois transfere para o WebAssembly de forma transparente assim que o pacote cliente é baixado. Combina o melhor dos dois, mas ao custo de um layout de projeto um pouco mais complexo.

Dica

A --interactivity bandeira corresponde à bandeira do template padrão dotnet new blazor com o mesmo nome, então tudo que você já sabe sobre os modos de renderização do Blazor é mantido.

Opções de Modelo

Ambos os templates expõem dotnet new opções para que você possa personalizar o projeto gerado desde o início. Passe-os na linha de comando ou escolha na tela de criação de projetos do Visual Studio (e na dotnet new interface interativa). As opções mais úteis:

• --user-audience (External | Internal | Both, padrão Both) — quem faz log. Usuários externos recebem contas locais (registro, login, redefinição de senha) além de quaisquer provedores externos que você habilite; Usuários internos entram apenas pela Microsoft / Entra; Ambos permitem cada um.
• --include-microsoft-login — acrescenta Login com a Microsoft. Ativado por padrão (e obrigatório para o público interno e para ambos). Armazene credenciais em Authentication:Microsoft.
• --include-google-login — adiciona o Login com o Google para usuários externos. Provisione credenciais OAuth e armazene-as sob Authentication:Google.
• --include-facebook-login — acrescenta Continue com o Facebook para usuários externos. Provisione um aplicativo e armazene suas credenciais em Authentication:Facebook.
• --include-machine-translation + --machine-translation-provider (Azure | DeepL | Google) — conecta um provedor de tradução automática para que a página de Administração de Localização possa traduzir arquivos de localização. Quando omitido, o painel de tradução permanece oculto e o registro é enviado conforme as orientações comentadas.
• --include-sample-content (padrão ativado) / --empty — inclua ou omita as páginas de exemplo e o estilo que demonstram padrões básicos de uso.
• --interactivity (Server | WebAssembly | Auto) — o modo de renderização Blazor (veja Modos de Interatividade acima). Não aplicável ao template React.
• --use-program-main — gerar um método explícito Program.Main em vez de instruções de nível superior.
• --framework (net10.0 | net9.0) — o arcabou-alvo.

Por exemplo, um portal Blazor auto-renderizado para ambos os públicos, com login do Google e tradução automática do Azure:

Dica

Execute dotnet new powerportalspro -h (ou dotnet new powerportalspro-react -h) para listar todas as opções e seu padrão. No Visual Studio, eles aparecem como caixas de seleção e menu suspenso na tela de criação de projetos.

O que está incluído

O modelo gera um projeto de portal totalmente funcional com o seguinte:

• Páginas de Exemplo — Páginas de listas de Contas e Contatos com MainGrid, além de páginas de detalhes com RecordContext, editores e SubGrids.
• Páginas de Identidade — Complete integração ASP.NET Core Identity com páginas de login, registro, esqueci senha, redefinição de senha, autenticação em dois fatores, confirmação de e-mail e gerenciamento de conta.
• Manipuladores de Segurança — Manipuladores de permissões pré-construídos para as tabelas de Conta e Contato, demonstrando padrões de segurança em nível de tabela e registro.
• Layout — Um MainLayout com PageLayout, menus de navegação para desktop e celular, configurações do site e suporte a temas.
• Localização — Um arquivo de localização JSON (app.en.json) com rótulos de navegação e strings específicas de página.
• Configuração — appsettings.json com marcadores para as configurações de conexão Dataverse.

Entendendo Program.cs

O Program.cs arquivo é onde todos os serviços são registrados e o pipeline de aplicação é configurado. Aqui está uma divisão de cada seção:

Modelo React

O guia abaixo descreve o modelo Program.csBlazor . O host do template React registra os mesmos serviços centrais — AddPowerPortalsProWebServer(), o Dataverse ConnectionOptions, localização, manipuladores de segurança e e-mail — mas omite o registro específico AddPowerPortalsProWebBlazorFluentUI() do Blazor, serve o React SPA e expõe os endpoints de autenticação via MapAuthEndpoints<PortalUser>() em vez de MapAdditionalIdentityEndpoints().

Cache distribuído

O template registra um cache distribuído baseado em memória. Em produção, substitua isso por um cache persistente como Redis ou SQL Server para melhor desempenho em múltiplas instâncias.

Registro Fluent UI

AddPowerPortalsProWebBlazorFluentUI() registra todos os componentes do Fluent UI Blazor usados pelos editores, grids e componentes de layout do PowerPortalsPro.

Serviços de servidor

AddPowerPortalsProWebServer() registra os serviços principais do lado do servidor, incluindo a camada de acesso a dados do Dataverse, aplicação de segurança, pipeline de interceptores e carregamento de localização.

Conexão Dataverse

A ConnectionOptions configuração especifica como o portal se autentica com o Dataverse. O modelo utiliza autenticação por Segredo do Cliente com credenciais armazenadas em appsettings.json ou Segredos de Usuário.

Dica

Para melhores práticas de segurança, armazene suas credenciais em Segredos de Usuário durante o desenvolvimento e no Azure Key Vault ou variáveis de ambiente em produção. Nunca comprometa segredos com o controle de versão.

Configuração de Localização

AddLocalizationDirectory registram diretórios contendo arquivos JSON de localização. Por padrão LocalizeAllAvailableTables é true, então rótulos, nomes de colunas e nomes de visualização são retirados automaticamente de todas as tabelas do Dataverse. Defina para false e use AddTableToLocalize / AddTablesToLocalize para restringir a localização a uma lista explícita.

Opções de Identidade

A IdentityOptions seção configura ASP.NET configurações de Identidade Central, como exigir confirmação por e-mail antes do login.

Tradução Automática (opcional)

Gerar o projeto para --IncludeMachineTranslation conectar a tradução automática para o painel de arquivos Translate na página de Administração de Localização. O modelo adiciona abaixo o pacote do PowerPortalsPro.Web.Server.Translation.* provedor escolhido e seu registro; escolha o provedor com --MachineTranslationProvider: Azure (o padrão), DeepL, ou Google. Forneça a chave do provedor via configuração / secretos de usuário sob Azure:Translation:Key, DeepL:Translation:Key, ou Google:Translation:Key para corresponder.

Dica

Sem essa opção, a página de Administrador de Localização ainda funciona — a visão geral do pipeline e os downloads por fonte/mesclados não são afetados; Apenas o painel de tradução permanece oculto, e o registro é enviado conforme as orientações comentadas para que você possa ativar manualmente depois.

Registro de Manipuladores de Segurança

Os manipuladores de permissão são registrados no contêiner DI para controlar o acesso CRUD para cada tabela. O modelo inclui handlers para Conta (acesso total) e Contato (somente leitura com atualizações baseadas no proprietário).

Configuração do E-mail

Ele EmailServiceOptions configura o endereço de e-mail do remetente usado para confirmação de conta e redefinição de senha. Isso é enviado pelo serviço de e-mail Dataverse.

Autenticação Microsoft (Opcional)

O modelo inclui código comentado para adicionar autenticação Microsoft Entra ID (Azure AD). Descomente e configure seu ID de Cliente e seu Segredo para habilitar login externo via contas Microsoft.

Middleware Pipeline

UsePowerPortalsProWebServer() adiciona o middleware PowerPortalsPro. UseLocalization() Habilita o sistema de localização. MapAdditionalIdentityEndpoints() registra o endpoint de login baseado em cookies usado pelas páginas de identidade.

Autenticação em Dois Fatores (Opcional)

O modelo inclui código comentado para habilitar a Autenticação de Dois Fatores usando códigos baseados em e-mail. Descomente a AuthenticatorTokenProvider opção e a AddDefaultTokenProviders() chamada para ativá-la.

Customizações Comuns

Após a estrutura do projeto, aqui estão os próximos passos comuns:

• Adicione handlers de permissões para quaisquer tabelas adicionais do Dataverse acessadas pelo seu portal.
• Toda tabela do Dataverse é localizada por padrão. Para optar por não usar uma área menor, defina LocalizeAllAvailableTables e false liste as tabelas que deseja via AddTableToLocalize.
• Registrar ITableRecordInterceptor implementações para lógica de negócios que rodem antes ou depois das operações de registro.
• Atualize os menus de navegação em NavMenu.razor, DesktopNavMenu.razor, e MobileNavMenu.razor para corresponder às páginas do seu portal.
• Adicione novas páginas com RecordContext, editores e grades para suas tabelas personalizadas do Dataverse.