XBOX PC Remote Iteration API
Fornece funções para copiar e excluir arquivos e para iniciar, retomar e encerrar jogos em dispositivos remotos baseados no Windows.Visão geral
A XBOX PC Remote Iteration API habilita fluxos de trabalho de desenvolvimento baseados em PC voltados para dispositivos Windows remotos. Ela fornece um conjunto de funções C para transferir arquivos de jogo entre um PC local e um dispositivo remoto, além de iniciar e gerenciar processos de jogo no dispositivo remoto. A API foi projetada para ciclos de iteração rápidos durante o desenvolvimento de jogos, permitindo que os desenvolvedores criem builds localmente e implantem e testem em hardware remoto sem gerenciamento manual de arquivos.Disponibilidade da API
Esta referência descreve a API mais recente. A menos que uma versão posterior seja especificada, as declarações públicas da API estão disponíveis no RIT 0.0.8-Preview, a versão inicial da API pública. Introduzida em identifica quando uma declaração foi adicionada. Suporte a partir de identifica quando uma opção declarada passou a funcionar. A introdução de uma declaração não implica que retornos de chamada ou configurações atualmente não usados estejam implementados. As seções Histórico de alterações descrevem alterações nas declarações ou no comportamento da API, não correções na documentação. Os rótulos de versão usam a versão do WinGet. A tabela de versões de lançamento mapeia cada rótulo para o pacote NuGet da API e para as versões da ferramenta de linha de comando.Quando usar
- Implantar builds de jogos de um PC local para um dispositivo Windows remoto durante o desenvolvimento.
- Copiar arquivos atualizados (cópia delta) para um dispositivo remoto para minimizar os tempos de transferência durante builds iterativos.
- Remover a saída de build obsoleta de um dispositivo remoto antes de implantar um novo build.
- Iniciar, suspender, retomar e encerrar processos de jogo em um dispositivo remoto a partir do seu PC de desenvolvimento.
- Automatizar fluxos de trabalho de build-implantação-teste em pipelines de integração contínua voltados para dispositivos Windows remotos.
- Criar ou integrar ferramentas personalizadas do estúdio para implantação em dispositivos Windows remotos, localmente ou em laboratórios de teste.
Quando NÃO usar
- Não use esta API para implantação de varejo ou de produção de jogos em consoles de usuários finais.
- Não use esta API para transferir arquivos entre dois dispositivos remotos; uma das extremidades deve ser o PC local.
- Não use esta API se o dispositivo remoto não tiver sido emparelhado e configurado para desenvolvimento remoto.
Pré-requisitos
- Pacote NuGet: Microsoft.GDK.RemoteIterationClientApi versão 0.1.0-preview.26.3.6001 ou posterior para a API base. APIs e opções posteriores exigem as versões identificadas em suas páginas de referência.
- Emparelhamento de dispositivos: o PC local e o dispositivo remoto devem estar emparelhados e confiar mutuamente um no outro, usando o aplicativo XBOX PC Toolbox para provisioná-los.
- wdEndpoint: o
wdEndpointdeve estar instalado e em execução no dispositivo remoto. A configuração do XBOX PC Toolbox instala e configura owdEndpointpor padrão. - Cabeçalho e biblioteca: inclua
WdRemoteIteration.he vincule awdremoteapi.lib.
Exemplo
O Remote Iteration Tools Sample é um aplicativo WPF em C# que demonstra como implantar, iniciar, retomar e encerrar jogos em um dispositivo remoto e cancelar uma implantação em andamento.Funções
Estruturas
Enumerações
Retornos de chamada
Modelo de threading
A XBOX PC Remote Iteration API foi projetada para operações de cópia de thread único. As seguintes regras se aplicam:- Uma cópia por vez. Somente uma chamada de WdRemoteCopy pode estar ativa a qualquer momento, independentemente do dispositivo de destino ou do caminho de destino. Chamar
WdRemoteCopyenquanto outra cópia já estiver em andamento resulta em comportamento indefinido. - Outras funções são seguras durante uma cópia. Funções como WdLaunchRemoteGame, WdTerminateRemoteGame, WdResumeRemoteGame e WdRegisterRemoteXboxGame podem ser chamadas a partir de threads separados enquanto uma cópia está em andamento.
- As operações remotas são de bloqueio. Funções como
WdRemoteCopyeWdDeleteRemoteFilesficam bloqueadas aguardando o resultado da operação, um erro ou um cancelamento observado.WdCancelRemoteCopyeWdCancelRemoteDeletenão são de bloqueio. - O cancelamento é thread-safe. WdCancelRemoteCopy e WdCancelRemoteDelete podem ser chamadas a partir de outro thread para sinalizar o cancelamento.
- Nenhum estado de conexão entre operações remotas. Cada chamada de operação remota estabelece sua própria conexão com o dispositivo remoto. Não há sessão persistente; por exemplo, se a conexão cair após a conclusão de WdLaunchRemoteGame, você ainda poderá chamar WdTerminateRemoteGame assim que a conectividade for restaurada.
Comportamento de repetição
A XBOX PC Remote Iteration API não repete automaticamente operações com falha no nível da API. Se uma operação falhar devido a uma interrupção de rede ou outro erro transitório, o chamador será responsável por tentar novamente.- Nenhuma repetição automática. Se uma operação de cópia falhar (por exemplo, devido à perda de conectividade de rede),
WdRemoteCopyretornará um erro. O chamador deverá invocar a função novamente para tentar outra vez. - Nenhum tempo limite configurável.
WdRemoteCopynão impõe um tempo limite à operação de cópia. Ela continua transferindo até a conclusão, até ocorrer um erro ou até ser cancelada por meio de WdCancelRemoteCopy. Em condições de rede degradadas, as transferências podem prosseguir muito lentamente em vez de falhar. - O progresso é preservado em caso de falha. Os arquivos copiados com êxito antes de uma falha permanecem no destino. Quando o chamador tenta a cópia novamente, o comportamento de cópia delta garante que somente arquivos incompletos ou ausentes sejam transferidos; os arquivos copiados anteriormente não são transferidos novamente.
- Erros de espaço em disco são relatados. Se o dispositivo de destino ficar sem espaço em disco durante uma cópia, a operação falhará com um erro em vez de travar.
- Resiliência no nível de transporte. A camada de transporte subjacente lida com a retransmissão de pacotes de baixo nível de forma transparente. Pequenas falhas de rede (como a perda de um único pacote) não fazem a operação falhar. No entanto, uma perda prolongada de conectividade acabará causando um erro.
- Padrão de repetição recomendado. Após uma falha de
WdRemoteCopy, basta chamarWdRemoteCopynovamente com os mesmos parâmetros. O comportamento de cópia delta minimiza o trabalho redundante transferindo apenas os arquivos ausentes ou incompletos no destino.
Cancelamento
A XBOX PC Remote Iteration API fornece um modelo de cancelamento baseado em identificador para operações de cópia e exclusão de longa duração. O mesmo tipo WdCancellationHandle é usado para ambas. O chamador é responsável pelo ciclo de vida do identificador:- Crie um identificador chamando WdCreateCancellationHandle.
- Passe o identificador para WdRemoteCopy por meio do parâmetro
cancellationHandle. - A partir de um thread separado, chame WdCancelRemoteCopy com o identificador para cancelar a cópia em andamento.
WdCancelRemoteCopynão é de bloqueio. Depois que o cancelamento for sinalizado,WdRemoteCopypoderá retornarS_OKou uma falha. - Depois que
WdRemoteCopyretornar, feche o identificador chamando WdCloseCancellationHandle.
S_OK sem confirmar a conclusão no ponto de extremidade. A exclusão já iniciada no ponto de extremidade continua de forma independente; o cancelamento não restaura os itens excluídos.
Raízes comuns
Raízes comuns são locais conhecidos pré-configurados no dispositivo remoto para os quais os jogos normalmente são copiados ou a partir dos quais são iniciados. Em vez de especificar um caminho absoluto completo, os chamadores podem se referir a esses locais por alias usando o campocommonRootAlias em WdCopyOptions ou WdLaunchOptions.
Para operações de cópia, o caminho remoto é destinationPath para CopyTo e sourcePath para CopyFrom. Se esse caminho for absoluto, o commonRootAlias será ignorado. Quando for relativo, ele será resolvido em relação à raiz comum identificada pelo alias. Se nenhum alias for especificado, o local padrão da raiz comum será usado.
Códigos de erro
Para obter uma lista completa dos códigos de erro específicos da API, incluindo descrições, causas raiz e orientações de solução de problemas, confira Códigos de erro da XBOX PC Remote Iteration API.Controle de versão, manutenção e distribuição
Para obter os números de versão do NuGet da API, do WinGet e dos executáveis, confira Versões de lançamento do XBOX PC Remote Iteration. A API do Remote Iteration Tools (RIT) segue o Versionamento Semântico 2.0.0 (MAJOR.MINOR.PATCH) para fornecer expectativas claras sobre compatibilidade, atualizações e suporte de longo prazo. Todas as bibliotecas públicas da API do RIT são distribuídas via NuGet, permitindo o gerenciamento de dependências e fluxos de trabalho de atualização padrão.
Modelo de controle de versão
As expectativas de compatibilidade abaixo se aplicam a versões que não são de visualização. Para pacotes de visualização, consulte o histórico de alterações específico da API para verificar alterações de declaração, layout e comportamento antes de atualizar.Versões PATCH
As atualizaçõesPATCH fornecem correções de bugs e melhorias de confiabilidade. Essas atualizações não alteram os contratos da API nem o comportamento em tempo de execução e são atualizações seguras de substituição direta. Atualizar para uma versão PATCH mais recente não requer alterações de código.
Versões MINOR
As atualizaçõesMINOR introduzem novas APIs ou evoluem a funcionalidade existente de forma compatível com versões anteriores. Quando houver planos de alterar ou remover APIs no futuro, elas serão claramente marcadas como preteridas, dando aos desenvolvedores tempo para migrar. As atualizações de dependências são revisadas para garantir a compatibilidade dentro da mesma versão MAJOR.
Versões MAJOR
As atualizaçõesMAJOR representam alterações interruptivas intencionais. Essas versões podem exigir alterações de código ou atualizações de dependências e são acompanhadas de orientações claras de migração. A atualização para uma nova versão MAJOR é tratada como uma decisão explícita e opcional, alinhada aos ciclos normais de validação e lançamento.
Modelo de manutenção e suporte
Depois que uma versãoMAJOR ou MINOR da API do RIT é lançada publicamente, ela entra em um período de manutenção ativa com uma janela de suporte prevista de aproximadamente 18 meses. Durante esse período:
- Versões
PATCHsão aprovadas para corrigir bugs e melhorar a confiabilidade das versões com suporte. - À medida que novas versões são lançadas e patches e pequenas alterações melhoram as versões existentes e corrigem bugs, várias versões
MAJOReMINORpodem receber manutenção simultaneamente. - Versões
PATCHnão estendem o tempo de manutenção de uma versãoMAJORouMINOR. - Novos recursos são introduzidos somente em versões
MINORouMAJORmais recentes e não são portados para versões anteriores.
MAJOR ou MINOR mais recente com suporte.
Expectativas de atualização
Recomenda-se que os desenvolvedores se mantenham atualizados dentro de uma versãoMAJOR, adotando as atualizações PATCH e MINOR. As atualizações de versão MAJOR devem ser planejadas e validadas explicitamente para garantir a compatibilidade com os fluxos de trabalho de produção.
Compatibilidade de versões entre a API e o wdEndpoint
A biblioteca de cliente da API do RIT e owdEndpoint em execução no dispositivo remoto devem sempre ser mantidos em versões compatíveis. Usar uma versão mais recente da API com um wdEndpoint mais antigo pode resultar em erros E_SERVERTOOOLD ou em comportamento inesperado. Para garantir o comportamento correto, a compatibilidade total com versões anteriores e o suporte aos recursos mais recentes da API, é recomendável atualizar o wdEndpoint em todos os dispositivos remotos sempre que a biblioteca de cliente da API for atualizada. Consulte as notas de versão do pacote NuGet para conhecer os requisitos mínimos de versão do wdEndpoint.