> 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/agente-realmjoin/realmjoin-client/native-choco-runtime.md).

# Native Choco Runtime

A Native Choco Runtime é o próprio motor de instalação de pacotes no processo do RealmJoin que substitui o binário desatualizado Chocolatey 0.10.3, mantendo-se totalmente compatível com os pacotes existentes.

{% hint style="info" %}
O Native Choco Runtime foi introduzido com **RealmJoin Agent 4.21.6 (Beta)**. O recurso é **opcional**: os clientes existentes continuam usando o mecanismo clássico do Chocolatey até que você habilite explicitamente o runtime nativo.
{% endhint %}

## O que é

Quando o RealmJoin Agent instala pacotes de software fora do Intune (veja [instalação de pacotes](https://docs.realmjoin.com/pt/agente-realmjoin/realmjoin-client/deploy-apps.md#package-installation)), ele tradicionalmente dependia de [Chocolatey](https://chocolatey.org/) como o mecanismo subjacente de pacotes. O RealmJoin fornecia uma versão fixa e fortemente modificada da CLI Chocolatey de código aberto — versão **0.10.3** — distribuída como `choco.exe` ao abrigo de `C:\ProgramData\chocolatey\`.

O **Native Choco Runtime** substitui esse binário Chocolatey incluído pela **implementação própria, desenvolvida especificamente para esse fim** que é executada **no próprio processo** dentro do serviço do RealmJoin. Ela *emula* Chocolatey: ele entende o mesmo formato de pacote (`.nupkg`) e se comporta da mesma forma do ponto de vista do autor do pacote e do administrador, mas já não depende da antiga base de código Chocolatey 0.10.3.

Em outras palavras, os pacotes que você já usa continuam funcionando sem alterações — apenas o mecanismo subjacente muda.

## Como funciona

* **Mecanismo no próprio processo.** As instalações de pacotes são executadas dentro do serviço do RealmJoin em vez de chamar um script externo `choco.exe`. O `chocolateyInstall.ps1` de cada pacote é executado em um espaço de execução do PowerShell no próprio processo.
* **Armazenamento isolado.** O runtime nativo instala-se em seu **próprio** raiz, `C:\ProgramData\RealmJoin\choco\` (com `lib\`, `extensions\`e `logs\` subpastas). Ele nunca grava no estado do Chocolatey clássico em `C:\ProgramData\chocolatey\` e nunca altera a variável de ambiente em nível de máquina `ChocolateyInstall` . Isso 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 do pacote declaradas no `.nuspec` (como o [RealmJoin Core Choco Extension](https://docs.realmjoin.com/pt/agente-realmjoin/recommended-packages.md#realmjoin-core-choco-extension)) são resolvidas e instaladas automaticamente a partir das suas origens configuradas.
* **`choco.exe` shim.** Alguns scripts de pacote chamam `choco.exe` diretamente. Para mantê-los funcionando, o runtime implanta um pequeno shim para `%ProgramFiles%\RealmJoin\choco-shim\choco.exe` que redireciona essas chamadas de volta para o mecanismo em processo em vez de para o Chocolatey clássico. O shim não é adicionado ao sistema `PATH`; ele só é disponibilizado aos scripts de pacote enquanto são executados.

## Compatibilidade

O Native Choco Runtime foi projetado como um **substituto pronto para uso**:

* Os pacotes existentes do RealmJoin (incluindo tudo do [Package Store](https://docs.realmjoin.com/pt/gestao-de-aplicacoes/packages/package-store.md)) são instalados e desinstalados da mesma forma.
* Os argumentos / parâmetros de pacote configurados no RealmJoin Portal continuam funcionando.
* O [RealmJoin Core Choco Extension](https://docs.realmjoin.com/pt/agente-realmjoin/recommended-packages.md#realmjoin-core-choco-extension) os cmdlets auxiliares usados dentro dos scripts de pacote continuam disponíveis.
* [ESP do RealmJoin](https://docs.realmjoin.com/pt/agente-realmjoin/realmjoin-client/realmjoin-esp.md) / Autopilot são suportados: em um dispositivo novo com o runtime nativo habilitado, `winchoco` os pacotes são instalados nativamente durante o registro, com suas dependências resolvidas automaticamente.

{% hint style="warning" %}
Como este runtime está em beta, recomendamos validar seus pacotes mais importantes em um anel piloto antes de implantá-lo em todo o tenant. Por favor, reporte quaisquer diferenças de comportamento ao Suporte do RealmJoin para que possamos resolvê-las antes da disponibilidade geral.
{% endhint %}

## Como usá-lo

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

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

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

As seguintes configurações controlam o comportamento:

<table><thead><tr><th>Configuração</th><th width="120">Padrão</th><th>Significado</th></tr></thead><tbody><tr><td><code>Chocolatey.Enabled</code></td><td><code>falso</code></td><td>O RealmJoin gerencia pacotes do tipo Chocolatey no dispositivo.</td></tr><tr><td><code>Chocolatey.UseNativeRuntime</code></td><td><code>falso</code></td><td>Interruptor principal. Quando <code>falso</code>, as instalações ainda passam 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>Relevante apenas quando <code>UseNativeRuntime = true</code>. Quando <code>verdadeiro</code>, qualquer script de pacote que chame um binário externo <code>choco.exe</code> falha de forma explícita em vez de ser encaminhado pelo shim — útil para revelar scripts que ainda dependem de um binário externo.</td></tr></tbody></table>

{% stepper %}
{% step %}

### Habilite-o primeiro para um grupo piloto

Abra as configurações de um **grupo** que contenha um pequeno conjunto de dispositivos piloto e defina `Chocolatey.UseNativeRuntime` a `verdadeiro` a configuração lá. Como as configurações de grupo têm precedência sobre o padrão em todo o tenant, apenas esses dispositivos mudam para o novo mecanismo.
{% endstep %}

{% step %}

### Valide seus pacotes

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

{% step %}

### Implante-o em todo o tenant

Quando estiver confiante, defina `Chocolatey.UseNativeRuntime` a `verdadeiro` pois o **padrão em todo o tenant** para que todos os clientes o utilizem. Grupos individuais ainda podem optar por não usá-lo, se você precisar mantê-los temporariamente no mecanismo clássico.
{% endstep %}
{% endstepper %}

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

## Qual é o padrão

O Native Choco Runtime está **desabilitado por padrão** (`Chocolatey.UseNativeRuntime = false`). Os clientes continuam usando o mecanismo clássico Chocolatey 0.10.3 empacotado até que um administrador habilite o runtime nativo — seja em todo o tenant ou para um grupo específico. Isso permite adotar o novo runtime no seu próprio ritmo e revertê-lo com a mesma facilidade enquanto o recurso está em beta.

## Migrando dispositivos existentes

O runtime nativo e o Chocolatey clássico **coexistir** em um dispositivo pelo tempo necessário. Quando você habilita o runtime nativo em um dispositivo que já possui pacotes instalados pelo Chocolatey clássico:

* Os pacotes existentes gerenciados pelo RealmJoin continuam funcionando e são **não** reinstalados apenas porque o runtime mudou — o estado instalado é mantido na mudança, portanto não há enxurrada de reinstalações.
* Novas instalações e atualizações passam pelo runtime nativo; a instalação clássica permanece no disco, intocada, até ser removida explicitamente.

{% hint style="info" %}
A remoção do Chocolatey clássico em toda a frota está planejada como uma etapa separada e coordenada. Até lá, o runtime nativo convive tranquilamente com uma instalação clássica remanescente, portanto não há um prazo rígido para limpá-la.
{% endhint %}

Para um dispositivo individual (por exemplo, durante suporte ou QA), um administrador pode retirar uma máquina do Chocolatey clássico com o verbo do shim `migre` a partir de um **com privilégios elevados** terminal:

{% code overflow="wrap" %}

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

# Reinstale os pacotes com estado por meio do runtime nativo e, em seguida, remova 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). Ele é **não** o mecanismo para distribuir a mudança em toda a frota — use as configurações de tenant/grupo para isso.
{% endhint %}

## Logs e solução de problemas

As instalações do runtime nativo gravam um log por pacote em:

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

(mantido para as 10 entradas mais recentes por pacote). Isso é separado do `C:\ProgramData\chocolatey\logs\`. Ao coletar logs para uma solicitação de suporte, inclua a `C:\ProgramData\RealmJoin\` pasta conforme descrito em [Problemas de instalação de pacotes](https://docs.realmjoin.com/pt/resolucao-de-problemas-e-faq/troubleshooting/package-installation-issues.md).

### Referência de arquivo e caminho

| 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 do PowerShell importados automaticamente. |
| `C:\ProgramData\RealmJoin\choco\logs\<id>`        | Logs 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
