> 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 mecanismo clássico do Chocolatey até que você 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)), ele tradicionalmente dependia de [Chocolatey](https://chocolatey.org/) como o mecanismo subjacente de pacotes. O RealmJoin fornecia 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\`.

A **Native Choco Runtime** substitui esse binário do Chocolatey incluído pelo **próprio RealmJoin, uma implementação concebida especificamente** que é executada **em processo** dentro do serviço do RealmJoin. Ele *faz shim de* Chocolatey: entende 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 você já usa continuam funcionando sem alterações — apenas o mecanismo por baixo deles muda.

## Como funciona

* **Mecanismo em processo.** As instalações de pacotes são executadas dentro do serviço do RealmJoin em vez de chamar um `choco.exe`. Os `chocolateyInstall.ps1` de cada pacote é executado em um espaço de execução PowerShell em processo.
* **Armazenamento isolado.** O runtime nativo instala-se na sua **própria** raiz, `C:\ProgramData\RealmJoin\choco\` (com subpastas `lib\`, `extensions\`, e `logs\` ). Ele nunca escreve no estado do Chocolatey clássico em `C:\ProgramData\chocolatey\` e nunca altera a variável de ambiente `ChocolateyInstall` em todo o sistema. 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 de 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 funcionando, o runtime implanta um pequeno shim em `%ProgramFiles%\RealmJoin\choco-shim\choco.exe` que encaminha essas chamadas de volta para o mecanismo em processo em vez de para o Chocolatey clássico. O shim não é adicionado ao `PATH`do sistema; ele só fica disponível para os scripts de pacote enquanto são executados.

## Compatibilidade

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

* Os pacotes existentes do RealmJoin (incluindo tudo do [Loja de Pacotes](/pt/gestao-de-aplicacoes/packages/package-store.md)) instalam e desinstalam da mesma forma.
* Os argumentos / params de pacote configurados no RealmJoin Portal continuam a funcionar.
* A [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.
* [ESP do RealmJoin](/pt/realmjoin-agent/realmjoin-client/realmjoin-esp.md) / Autopilot são suportados: em um dispositivo novo com o runtime nativo ativado, `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 os seus pacotes mais importantes em um anel piloto antes de implantá-lo em todo o Tenant. Reporte quaisquer diferenças comportamentais ao Suporte do RealmJoin para que possamos corrigi-las antes da disponibilidade geral.
{% endhint %}

## Como usá-lo

O runtime é selecionado por meio de uma **definição do RealmJoin**, para que você possa controlá-lo centralmente em vez de mexer em clientes individuais. As definições do RealmJoin em cascata significam que você pode definir um **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 definição: `Chocolatey.UseNativeRuntime`

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

As definições a seguir controlam o comportamento:

<table><thead><tr><th>Definição</th><th width="120">Padrão</th><th>Significado</th></tr></thead><tbody><tr><td><code>Chocolatey.Enabled</code></td><td><code>false</code></td><td>O RealmJoin gerencia pacotes do tipo Chocolatey no dispositivo.</td></tr><tr><td><code>Chocolatey.UseNativeRuntime</code></td><td><code>false</code></td><td>Interruptor principal. Quando <code>false</code>, as instalações ainda passam pelo <code>choco.exe</code>. Quando <code>verdadeiro</code>clássico, <code>winchoco</code> todas as instalações passam pelo runtime nativo em processo.</td></tr><tr><td><code>Chocolatey.DisableShim</code></td><td><code>false</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 de forma explícita em vez de ser encaminhado pelo 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` lá. Como as definições de grupo têm precedência sobre o padrão em todo o Tenant, apenas esses dispositivos passam para o novo mecanismo.
{% endstep %}

{% step %}

### Valide os seus pacotes

Deixe que os dispositivos piloto executem suas atribuições normais de pacotes e atualizações. 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 %}

### Implante-o em todo o Tenant

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

{% hint style="info" %}
A configuração segue o mesmo modelo de definição de 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** configurações do Tenant).
{% endhint %}

## Qual é o padrão

Native Choco Runtime é **desativado por padrão** (`Chocolatey.UseNativeRuntime = false`). Os clientes continuam a usar o mecanismo clássico incluído do Chocolatey 0.10.3 até que um administrador ative 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 a funcionalidade estiver em beta.

## Migração de dispositivos existentes

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

* Os pacotes existentes gerenciados pelo RealmJoin continuam funcionando e **não** não são reinstalados só porque o runtime mudou — o estado instalado deles é preservado na transição, então não há tempestade de reinstalação.
* As 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 aceita coexistir com uma instalação clássica remanescente, então não há um prazo rígido para limpá-la.
{% endhint %}

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

{% code overflow="wrap" %}

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

# Reinstale pacotes com estado via 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 **auxiliar de administração para um único dispositivo** (suporte, dev/QA, limpeza pontual). Não é **não** o mecanismo para implantar a mudança em toda a frota — use as definições de Tenant/grupo para isso.
{% endhint %}

## Registos e resolução de problemas

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

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

(mantido apenas com as 10 entradas mais recentes por pacote). Isso é separado do `C:\ProgramData\chocolatey\logs\`clássico do Chocolatey. Ao coletar registos para uma solicitação 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 do 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` | A `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.