Valide uma mudança do framework num app REAL — pacotes, global.json, restore, o caminho inteiro do consumidor — sem cortar versão nem correr pipeline. O primeiro consumidor do Trilho W provou a sua migração assim: frames byte-idênticos entre o build por pacotes e o build por source.

No checkout do framework:

dotnet pack -c Release -p:PackageVersion=1.0.0-dev -o artifacts/local-feed

1.0.0-dev nunca colide com uma versão publicada, o Sdk.Native deriva a versão de cada pacote irmão da sua própria, e os samples não empacotam — o feed é só produto. No app:

•

global.json: { "msbuild-sdks": { "eQuantic.UI.Sdk.Native": "1.0.0-dev" } } (ou eQuantic.UI.Sdk)

•

nuget.config: <clear />, depois o feed local PRIMEIRO, nuget.org a seguir

•

o ficheiro de projeto: Sdk="eQuantic.UI.Sdk.Native", sem atributo de versão

Depois de cada repack, limpe a cópia em cache e restaure de novo — o NuGet nunca baixa outra vez uma versão que já tem. O ClearEQuanticCache vive no Directory.Build.targets do framework, então corra a partir desse checkout; ele remove todo pacote equantic.* do cache do NuGet reativamente (uma lista mantida à mão já deixou passar todos os pacotes nativos):

dotnet msbuild -t:ClearEQuanticCache src/eQuantic.UI.Core/eQuantic.UI.Core.csproj

dotnet restore --force

Prova headless para um app nativo, sem janela: --Photon:ScreenshotPath out.png.

Arquivos-chave

Arquivo

Responsabilidade

Sdk/Sdk.targets

Resolve o Bun, instala os itens <BunPackage>, compila os componentes

Server.csproj

Resolve o Bun na árvore de código, empacota o runtime.js

Runtime.{OS}.csproj

Empacota o executável do Bun para cada plataforma

Targets do MSBuild (ordem de execução)

No SDK (consumidor)

ResolveBunZipPath - encontra o .zip do Bun no cache do NuGet

EnsureBunExtracted - extrai o executável se preciso

ResolveBunPath - define $(BunPath) para uso posterior

InstallBunPackages - instala os itens <BunPackage> via bun add (veja BunPackage)

CompileEQuanticUI - transpila C# → TypeScript → JavaScript

CopyEQuanticRuntime - copia o runtime.js do pacote Runtime para wwwroot/\_equantic/

No Server (desenvolvimento)

ResolveBunForServer - encontra o Bun na árvore de código

BundleRuntime - compila boot.ts → runtime.js

Arquitetura de pacotes e autocontenção

O eQuantic.UI segue uma arquitetura de pacotes autocontidos, em que cada pacote gerencia os próprios artefatos. O SDK age como orquestrador, referenciando os outros pacotes pelas propriedades $(Pkg*) do NuGet.

Princípios da arquitetura

Antes (problemático):

Pacote SDK ❌

├─ runtime.js embarcado (copiado do Runtime)

└─ arquivos *.cs embarcados (copiados do Components)

Problemas: acoplamento forte, conflitos de versão, duplicação de artefatos

Depois (correto):

Pacote Runtime ✅

└─ tools/runtime/runtime.js (autocontido)

Pacote Components ✅

└─ tools/source/*.cs (autocontido)

Pacote SDK ✅

└─ Referencia os outros pacotes via $(PkgeQuantic_UI_*)

Benefícios: desacoplamento, versionamento correto, sem duplicação

Entrega do runtime.js

1. Empacotamento (desenvolvimento)

Durante o dotnet pack do eQuantic.UI.Runtime:

<Content Include="dist\index.js" PackagePath="tools\runtime\runtime.js"

Condition="Exists('dist\index.js')" />

</ItemGroup>

O pacote Runtime embarca o próprio artefato JavaScript compilado.

2. Entrega (build do consumidor)

Durante o dotnet build, o target CopyEQuanticRuntime do SDK executa:

<Target Name="CopyEQuanticRuntime" AfterTargets="CompileEQuanticUI"

Condition="'$(EnableEQuanticUICompilation)' == 'true'">

<_RuntimeSourcePath Condition="'$(PkgeQuantic_UI_Runtime)' != ''">

$(PkgeQuantic_UI_Runtime)/tools/runtime/runtime.js

</_RuntimeSourcePath>

<_RuntimeSourcePath Condition="'$(_RuntimeSourcePath)' == ''">

$(MSBuildThisFileDirectory)../../eQuantic.UI.Runtime/dist/index.js

</_RuntimeSourcePath>

<_RuntimeDestPath>$(MSBuildProjectDirectory)/$(EQuanticOutputPath)runtime.js</_RuntimeDestPath>

</PropertyGroup>

<Error Text="eQuantic.UI: Runtime not found. Ensure eQuantic.UI.Runtime package is installed."

Condition="'$(_RuntimeSourcePath)' == '' Or !Exists('$(_RuntimeSourcePath)')" />

</Target>

Entrega das fontes do Components

1. Empacotamento (desenvolvimento)

Durante o dotnet pack do eQuantic.UI.Components:

</ItemGroup>

O pacote Components embarca os próprios arquivos de código C# para a resolução de tipos do compilador.

2. Compilação (build do consumidor)

Durante o dotnet build, o target CompileEQuanticUI do SDK executa:

<_StandardComponentsDir Condition="'$(PkgeQuantic_UI_Components)' != ''">

$(PkgeQuantic_UI_Components)/tools/source

</_StandardComponentsDir>

<_StandardComponentsDir Condition="'$(_StandardComponentsDir)' == ''">

$(MSBuildThisFileDirectory)../../eQuantic.UI.Components

</_StandardComponentsDir>

</PropertyGroup>

<Error Text="eQuantic.UI: Standard components not found. Ensure eQuantic.UI.Components package is installed."

Condition="'$(_StandardComponentsDir)' == '' Or !Exists('$(_StandardComponentsDir)')" />

</Target>

Principais benefícios da arquitetura

•

Desacoplamento: o SDK não embarca artefatos de outros pacotes

•

Versionamento correto: o consumidor pode usar Runtime 0.1.3 + SDK 0.1.2 de forma independente

•

Sem duplicação: cada artefato existe só no pacote de origem dele

•

Flexibilidade: os pacotes evoluem independentemente, sem acoplamento forte

•

Interface clara: o SDK referencia os pacotes por propriedades bem definidas do NuGet ($(Pkg*))

•

Alternativa em desenvolvimento: os caminhos da árvore de código funcionam para o desenvolvimento do framework

Estratégia de bundle único do runtime

O Runtime usa a configuração inlineDynamicImports: true do Vite para criar um bundle único:

// eQuantic.UI.Runtime/vite.config.ts

export default defineConfig({

build: {

rollupOptions: {

output: {

inlineDynamicImports: true, // ← Cria um bundle único

});

Por que um bundle único?

•

Entrega simplificada: só um arquivo para copiar (runtime.js)

•

Sem gestão de chunks: evita problemas com chunks separados de logger-_.js, error-overlay-_.js

•

Distribuição confiável: garante que todos os recursos do runtime (logger, overlay de erro) estejam incluídos

•

Tamanho pequeno: ~49KB minificado com todos os recursos incluídos

Sem isso, o Vite criaria chunks separados para os imports dinâmicos, e o SDK precisaria copiar vários arquivos com nomes baseados em hash.

PREVIOUSAssets-pt-BR

NEXTBunPackage-pt-BR

ON THIS PAGE

Fluxo visual

Origem do Bun por componente

Requisitos do consumidor

Consumir um SDK não lançado a partir de pacotes locais