> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/pt/realmjoin-agent/realmjoin-client/native-choco-runtime.md).

# Runtime nativo do Choco

{% hint style="info" %}
O Native Choco Runtime foi introduzido com **RealmJoin Agent 4.21.6 (Beta)**. A funcionalidade é **opcional**: os clientes existentes continuam a usar o motor clássico do Chocolatey até que ative explicitamente o runtime nativo.
{% endhint %}

## O que é

Quando o RealmJoin Agent instala pacotes de software fora do Intune (ver [instalação de pacotes](/pt/realmjoin-agent/realmjoin-client/deploy-apps.md#package-installation)), tradicionalmente tem recorrido a [Chocolatey](https://chocolatey.org/) como motor subjacente de pacotes. O RealmJoin forneceu uma compilação fixada e fortemente corrigida da CLI open-source do Chocolatey — versão **0.10.3** — incluída como `choco.exe` em `C:\ProgramData\chocolatey\`.

O **Native Choco Runtime** substitui esse binário do Chocolatey incluído pela **sua própria implementação, concebida para esse fim** que é executada **em processo** dentro do serviço RealmJoin. Ele *atua como shim para* Chocolatey: compreende o mesmo formato de pacote (`.nupkg`) e comporta-se da mesma forma do ponto de vista do autor do pacote e do administrador, mas já não depende da base de código envelhecida do Chocolatey 0.10.3.

Em outras palavras, os pacotes que já usa continuam a funcionar inalterados — só o motor por trás deles muda.

## Como funciona

* **Motor em processo.** As instalações de pacotes correm dentro do serviço RealmJoin em vez de invocar um `choco.exe`. Os `chocolateyInstall.ps1` de cada pacote é executado numa runspace do PowerShell em processo.
* **Armazenamento isolado.** O runtime nativo instala-se na sua **própria** raiz, `C:\ProgramData\RealmJoin\choco\` (com `lib\`, `extensions\`, e `logs\` subpastas). Nunca escreve no estado do Chocolatey clássico em `C:\ProgramData\chocolatey\` e nunca altera a variável de ambiente de todo o sistema `ChocolateyInstall` . Isto significa que o runtime nativo e um Chocolatey clássico já existente podem **coexistir** no mesmo dispositivo.
* **Resolução automática de dependências.** As dependências dos pacotes declaradas no `.nuspec` (como o [RealmJoin Core Choco Extension](/pt/realmjoin-agent/recommended-packages.md#realmjoin-core-choco-extension)) são resolvidas e instaladas automaticamente a partir das suas fontes configuradas.
* **`choco.exe` shim.** Alguns scripts de pacote chamam `choco.exe` diretamente. Para manter esses scripts a funcionar, o runtime implementa um pequeno shim para `%ProgramFiles%\RealmJoin\choco-shim\choco.exe` que encaminha essas chamadas de volta para o motor em processo em vez do Chocolatey clássico. O shim não é adicionado ao `PATH`do sistema; só é disponibilizado para os scripts de pacote enquanto estes são executados.

## Compatibilidade

O Native Choco Runtime foi concebido como um **substituto direto**:

* Os pacotes existentes do RealmJoin (incluindo tudo o que vem da [Loja de Pacotes](/pt/gestao-de-aplicacoes/packages/package-store.md)) instalam e desinstalam da mesma forma.
* Os argumentos/parâmetros de pacote configurados no RealmJoin Portal continuam a funcionar.
* O [RealmJoin Core Choco Extension](/pt/realmjoin-agent/recommended-packages.md#realmjoin-core-choco-extension) os cmdlets auxiliares usados dentro dos scripts de pacote continuam disponíveis.
* [RealmJoin ESP](/pt/realmjoin-agent/realmjoin-client/realmjoin-esp.md) / Autopilot são suportados: num dispositivo novo com o runtime nativo ativado, `winchoco` os pacotes são instalados nativamente durante o registo, com as suas dependências resolvidas automaticamente.

{% hint style="warning" %}
Como este runtime está em beta, recomendamos validar os seus pacotes mais importantes num anel-piloto antes de o implementar para todo o tenant. Reporte quaisquer diferenças de comportamento ao RealmJoin Support para que as possamos corrigir antes da disponibilidade geral.
{% endhint %}

## Como usar

O runtime é selecionado através de uma **definição**, por isso pode controlá-lo centralmente em vez de tocar em clientes individuais. As definições do RealmJoin são hierárquicas, o que significa que pode definir um **padrão para todo o tenant** e, quando necessário, **substituí-lo para grupos específicos** (e os objetos dentro deles).

{% hint style="info" %}
Chave da definição: `Chocolatey.UseNativeRuntime`

Valor da definição: `verdadeiro` / `falso`
{% endhint %}

As seguintes definições controlam o comportamento:

<table><thead><tr><th>Definição</th><th width="120">Predefinição</th><th>Significado</th></tr></thead><tbody><tr><td><code>Chocolatey.Enabled</code></td><td><code>falso</code></td><td>O RealmJoin gere pacotes do tipo Chocolatey no dispositivo.</td></tr><tr><td><code>Chocolatey.UseNativeRuntime</code></td><td><code>falso</code></td><td>Interruptor mestre. Quando <code>falso</code>, as instalações continuam a passar pelo Chocolatey clássico, <code>choco.exe</code>. Quando <code>verdadeiro</code>todas <code>winchoco</code> as instalações passam pelo runtime nativo em processo.</td></tr><tr><td><code>Chocolatey.DisableShim</code></td><td><code>falso</code></td><td>Só é relevante quando <code>UseNativeRuntime = true</code>. Quando <code>verdadeiro</code>, qualquer script de pacote que chame um <code>choco.exe</code> externo falha explicitamente em vez de ser encaminhado através do shim — útil para expor scripts que ainda recorrem a um binário externo.</td></tr></tbody></table>

{% stepper %}
{% step %}

### Ative-o primeiro para um grupo-piloto

Abra as definições de um **grupo** do RealmJoin que contenha um pequeno conjunto de dispositivos piloto e defina `Chocolatey.UseNativeRuntime` para `verdadeiro` aí. Como as definições de grupo têm precedência sobre o padrão para todo o tenant, só esses dispositivos mudam para o novo motor.
{% endstep %}

{% step %}

### Valide os seus pacotes

Deixe os dispositivos piloto executarem as suas atribuições e atualizações normais de pacotes. Confirme que as instalações são bem-sucedidas e verifique os registos se algo parecer errado (ver [Problemas de instalação de pacotes](/pt/resolucao-de-problemas-e-faq/troubleshooting/package-installation-issues.md)).
{% endstep %}

{% step %}

### Implemente-o em todo o tenant

Quando estiver confiante, defina `Chocolatey.UseNativeRuntime` para `verdadeiro` pois o **padrão para todo o tenant** para que todos os clientes o usem. Os grupos individuais ainda podem optar por sair se precisar de os manter temporariamente no motor clássico.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
A configuração segue o mesmo modelo de definição do tenant / substituição por grupo que as outras definições do agente descritas em [Definições gerais](/pt/administracao-e-definicoes/general.md) (por exemplo as **Configuração do cliente** e **Configuração do LAPS** definições do tenant).
{% endhint %}

## Qual é a predefinição

O Native Choco Runtime está **desativado por predefinição** (`Chocolatey.UseNativeRuntime = false`). Os clientes continuam a usar o motor clássico incluído do Chocolatey 0.10.3 até que um administrador ative o runtime nativo — seja para todo o tenant ou para um grupo específico. Isto permite adotar o novo runtime ao seu próprio ritmo e reverter da mesma forma enquanto a funcionalidade está em beta.

## Migração de dispositivos existentes

O runtime nativo e o Chocolatey clássico **coexistir** num dispositivo durante o tempo necessário. Quando ativa o runtime nativo num dispositivo que já tem pacotes instalados pelo Chocolatey clássico:

* Os pacotes existentes geridos pelo RealmJoin continuam a funcionar e não são **não** reinstalados só porque o runtime mudou — o estado instalado é transportado através da mudança, pelo que não há uma vaga de reinstalações.
* As novas instalações e atualizações passam pelo runtime nativo; a instalação clássica permanece no disco, inalterada, até ser removida explicitamente.

{% hint style="info" %}
A remoção do Chocolatey clássico em toda a frota está planeada como uma etapa separada e coordenada. Até lá, o runtime nativo coexistirá sem problemas com uma instalação clássica remanescente, pelo que não existe um prazo apertado para a limpar.
{% endhint %}

Para um dispositivo individual (por exemplo, durante apoio ou QA), um administrador pode retirar uma máquina do Chocolatey clássico com o verbo `migre` do shim a partir de uma shell **elevada** :

{% code overflow="wrap" %}

```powershell
# Pré-visualizar o que aconteceria, sem fazer alterações
& "C:\Program Files\RealmJoin\choco-shim\choco.exe" migrate --dry-run

# Reinstalar pacotes com estado através do runtime nativo e, em seguida, remover o clássico
& "C:\Program Files\RealmJoin\choco-shim\choco.exe" migrate --yes
```

{% endcode %}

{% hint style="warning" %}
`choco migrate` é um **assistente de administração para um único dispositivo** (suporte, dev/QA, limpeza pontual). É **não** o mecanismo para aplicar a alteração a toda a frota — use para isso as definições de tenant/grupo.
{% endhint %}

## Registos e resolução de problemas

As instalações do runtime nativo escrevem um registo por pacote em:

```
C:\ProgramData\RealmJoin\choco\logs\<package-id>\<timestamp>_<version>_<operation>.log
```

(mantidos com as 10 entradas mais recentes por pacote). Isto é separado dos registos do Chocolatey clássico em `C:\ProgramData\chocolatey\logs\`. Ao recolher registos para um pedido de suporte, inclua a pasta `C:\ProgramData\RealmJoin\` conforme descrito em [Problemas de instalação de pacotes](/pt/resolucao-de-problemas-e-faq/troubleshooting/package-installation-issues.md).

### Referência de ficheiros e caminhos

| Caminho                                           | Finalidade                                                |
| ------------------------------------------------- | --------------------------------------------------------- |
| `C:\ProgramData\RealmJoin\choco\lib\<id>`         | Raiz de instalação de pacotes do runtime nativo.          |
| `C:\ProgramData\RealmJoin\choco\extensions\<id>`  | Módulos auxiliares PowerShell importados automaticamente. |
| `C:\ProgramData\RealmJoin\choco\logs\<id>`        | Registos por instalação (últimos 10 por pacote).          |
| `C:\Program Files\RealmJoin\choco-shim\choco.exe` | O `choco.exe` shim.                                       |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.realmjoin.com/pt/realmjoin-agent/realmjoin-client/native-choco-runtime.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.