Introdução
MakePkg.exe é uma ferramenta que coloca conteúdo em um arquivo binário empacotado, conhecido como XBOX Virtual Container (XVC). Os pacotes para console têm a extensão de nome de arquivo .xvc e os pacotes para PC têm a extensão de nome de arquivo .msixvc. Além da diferença de extensão, um sufixo é adicionado ao nome do pacote para diferenciar os pacotes da Família XBOX One (_x) e da Família XBOX Series X|S (_xs). O MakePkg.exe usa o conteúdo do seu título e um arquivo de mapeamento como entrada para produzir pacotes criptografados usando uma chave de teste conhecida, uma chave gerada aleatoriamente ou uma chave estável segura para criptografia. A chave usada para criptografia depende de o pacote ser destinado a testes locais ou ao envio para a Microsoft para publicação. As seções a seguir detalham os casos de uso. O XML no arquivo de mapeamento tem duas finalidades. Primeiro, ele especifica o local dos arquivos que ficam disponíveis para o título em tempo de execução. Segundo, ele especifica o arquivo de bloco (chunk) ao qual cada arquivo pertence. Um conjunto de blocos, conhecido como conjunto de inicialização, é sempre instalado antes que um título possa ser executado. Os blocos restantes são instalados enquanto o título está em execução. Há APIs disponíveis para consultar o progresso da instalação dos blocos e para modificar a ordem de instalação dos blocos que ainda não foram instalados. Neste artigo:- Etapas durante o empacotamento
- Etapas recomendadas para empacotamento durante o desenvolvimento
- Teste de pacotes de instalação por streaming
- Práticas recomendadas
- Falhas de empacotamento causadas por conexões de dados abertas
- Recursos e orientações
- Confira também
Etapas durante o empacotamento
O processo de empacotamento do MakePkg inclui várias etapas.Validação do MicrosoftGame.config e da existência de arquivos
O comandomakepkg verifica se o arquivo MicrosoftGame.config no diretório de origem do conteúdo é válido e pode ser instalado.
Quando você executa o comando makepkg pack, ele garante que os arquivos referenciados no MicrosoftGame.config estejam no diretório de origem. Ele valida que esses arquivos estão incluídos no pacote para o conjunto de inicialização. Essa validação inclui binários, arquivos de imagem e quaisquer outros recursos.
Assinatura de binários
O XBOX Code Integrity (XCI) verifica e assina os arquivos do seu título. Como parte desse processo, ele modifica os cabeçalhos PE detectados nos arquivos antes de gravá-los no arquivo de pacote. Se a assinatura falhar, uma mensagem de erro será exibida. A mensagem inclui um comando para executar novamente o xcihash.exe manualmente e obter mais detalhes sobre a falha de assinatura.Criação do pacote
Assim que o MakePkg conclui as etapas de pré-validação, ele cria um arquivo de pacote. Em seguida, o MakePkg copia os arquivos de origem, incluindo os executáveis assinados, para o arquivo de pacote nos blocos especificados pelo arquivo de mapa XML.Somente console: a última etapa da criação do pacote envolve a incorporação de um arquivo do Game OS (GameOs.xvd). Esse arquivo faz parte do Microsoft Game Development Kit (GDK) e deve estar no diretório de layout ao lado do executável do seu jogo. O sinalizador
/gameos especifica um local de origem alternativo para o arquivo do Game OS.Criptografia
Assinatura de teste (criptografia padrão)
O comportamento padrão do MakePkg é criar pacotes com assinatura de teste, o que também é indicado ao usar a opção/lt ao chamar makepkg pack. A assinatura de teste criptografa o arquivo de pacote gerado usando uma chave de criptografia de teste conhecida, destinada à validação de testes de desempenho, para execução no XBOX e no PC. Embora o efeito da descriptografia do pacote em tempo real tenha sido projetado para ser transparente para o título, isso garante que quaisquer possíveis problemas de desempenho resultantes da criptografia sejam descobertos antes da certificação e da publicação final dos títulos. Os pacotes com assinatura de teste não se destinam a proteger criptograficamente o conteúdo, porque a criptografia usa uma chave fixa. Um pacote com assinatura de teste pode ser instalado em um Kit de Desenvolvimento usando xbapp install e em um PC de desenvolvimento usando wdapp install.
Criptografia com chave aleatória (opção /l)
A opção /l do MakePkg criptografa o arquivo de pacote com uma chave de criptografia gerada aleatoriamente. Além do pacote do seu título, o MakePkg /l gera um arquivo com um nome no formato PackageFullName_licenseName_GUID.EKB. (Observe o uso do caractere de sublinhado (_).) Os pacotes criados com a opção /l não podem ser instalados em um Kit de Desenvolvimento nem em um PC de desenvolvimento. Você deve testar seu título usando pacotes com assinatura de teste até que o título passe em todas as verificações e testes de pré-envio. Depois de atingir esse estado, execute o MakePkg com a opção /l antes do envio final para a Microsoft.
Recomendado: criptografia com chave estável (Genkey + opção /lk)
A opção/lk do Makepkg criptografa o pacote com uma chave estável (sempre a mesma) criada pelo comando makepkg genkey. Além do pacote do seu título, o makepkg /lk gera arquivos com nomes nos formatos PackageFullName_licenseName_GUID.EKB e PackageFullName_licenseName_GUID.CEKB. (Observe o uso do caractere de sublinhado (_).) Os pacotes criados com a opção /lk podem ser instalados em um Kit de Desenvolvimento, mas não em um PC de desenvolvimento. Para PCs, você deve testar seu título usando pacotes com assinatura de teste até que o título passe em todas as verificações e testes de pré-envio.
Este é o modo de criptografia recomendado para testes em kits de desenvolvimento e para envio, devido a estes benefícios:
- O packageutil compare pode gerar estimativas corretas do tamanho das atualizações (ao contrário de /l).
- Ele permite o upload delta seguro para o Partner Center usando o mesmo algoritmo que consoles e PCs usam para baixar atualizações de conteúdo.
- Ele pode ser instalado em devkits (ao contrário de
/l). - Ele usa material de chave de criptografia seguro e só pode ser descriptografado em ambientes específicos (ao contrário de
/lt).
/lt e /l, o modo /lk exige uma etapa adicional única para ser usado:
- Uma única vez: execute
makepkg genkey /ekb SECRET_KEY.lekbpara criar o arquivo SECRET_KEY.lekb. Esse é o Local Escrowed Key Blob (LEKB), que armazena a chave de conteúdo estável que criptografa seu pacote. Ele deve ser armazenado em um local seguro, com acesso restrito a quem precisa dele. Em uma configuração ideal, somente as máquinas/contas oficiais de build devem ter acesso a ele. - Criação do pacote: execute
makepkg pack /lk SECRET_KEY.lekb .... Isso cria um pacote criptografado usando a chave armazenada no arquivo SECRET_KEY.lekb. - Upload do pacote: os arquivos XVC e EKB são carregados no Partner Center normalmente. Os arquivos LEKB e CEKB não são carregados.
xbapp install instala automaticamente o arquivo CEKB necessário para carregar o pacote em um devkit XBOX. Se você estiver testando um cenário de
instalação diferente da instalação baseada em ferramentas (disco de jogo, armazenamento externo, transferência de console para console), use o comando xbapp installkey para
instalar somente o arquivo CEKB.
pode descriptografar o conteúdo dele.
pode instalar o pacote no próprio devkit, iniciar o pacote e usar o xbcp para copiar os arquivos para fora do pacote.
Validação de envio
O MakePkg executa automaticamente o Submission Validator (SubmissionValidator.dll) nos arquivos do título após criar o pacote. O objetivo do Submission Validator é verificar erros e problemas que podem causar dificuldades para os títulos posteriormente nos processos de ingestão, envio ou certificação na Microsoft ou em futuras atualizações de conteúdo. Você precisa corrigir todos os problemas detectados antes de poder gerar um pacote assinado para upload no Partner Center. O processo de validação de envio gera um arquivo de log XML detalhando a natureza e o local de quaisquer falhas. O processo grava esse arquivo de log no mesmo local especificado pelo parâmetro/pd do MakePkg para a saída do arquivo de pacote. Esse log pode conter falhas ou avisos. Você deve resolver as falhas antes de poder enviar um pacote para a Microsoft. Considere corrigir os avisos para garantir que os títulos estejam em conformidade com a política e com as orientações dos XBOX Requirements (XR).
Quando você carrega um pacote no Partner Center e o envia para o processo de ingestão, as verificações de validação são executadas novamente. Esse processo garante que o título seja verificado usando a versão mais recente do Submission Validator e que quaisquer problemas sejam detectados o mais cedo possível.
Testes de validação de envio
Os testes específicos evoluem com o tempo, à medida que a Microsoft identifica novos problemas. Passar nas verificações do Submission Validator não deve ser interpretado como uma indicação de que outros problemas não surgirão com o envio do título durante o processo de ingestão e certificação. Em vez disso, a intenção é apenas reduzir o tempo e o custo das rejeições resultantes de erros previsíveis. Além disso, embora o Submission Validator possa verificar determinados problemas relacionados à segurança, ele não deve ser visto como um teste de segurança para um título.
Você pode baixar a versão mais recente do Submission Validator no site XBOX Game Developer (XGD). Como a ferramenta pode evoluir em um ritmo diferente das versões do XBOX One Software Development Kit, certifique-se de estar usando a versão mais recente para evitar rejeições por falha de validação no processo de envio. Para obter a versão mais recente, confira XBOX Developer Downloads->XBOX One->Submission Validator.
Para obter mais informações sobre o Submission Validator, confira Submission Validator (SubmissionValidator.dll) na documentação do GDK.
Se você tiver dúvidas sobre o processo de validação, entre em contato com seu Representante de Conta da Microsoft.
Etapas recomendadas para empacotamento durante o desenvolvimento
Para criar pacotes durante o desenvolvimento, use as etapas a seguir. Usewdapp em vez de xbapp ao direcionar para PC.
- Faça iterações localmente usando pacotes com assinatura de teste e xbapp install no seu PC de desenvolvimento. MakePkg.exe pack /f Mapfile /d LooseContentDir /pd OutputFolder Para começar, confira XBOX Developer Downloads.
- Execute seu título iniciando-o pelo shell ou usando xbapp launch. xbapp install local-XVC-path ou xbapp install http-URI Para testar opções alternativas de instalação por streaming, confira Teste de pacotes de instalação por streaming mais adiante neste artigo.
- Teste a instalação do título a partir da unidade óptica usando um pacote com assinatura de teste gravado na pasta raiz de um disco Blu-ray. Depois de inserir o disco no Kit de Desenvolvimento XBOX, execute o comando a seguir. xbapp install XO:\XVC-file-name
-
Prepare seu envio final usando o mesmo comando de empacotamento do seu pacote com assinatura de teste, mas adicione o sinalizador
/l.
Teste de pacotes de instalação por streaming (PC)
Use o comandowdapp para instalar pacotes no PC de teste.
Atualmente, o pacote MSIXVC de teste deve existir em uma unidade física no PC de teste ou em um servidor Web. Em uma atualização futura, será adicionada a instalação a partir de compartilhamentos UNC (Universal Naming Convention).
Teste de pacotes de instalação por streaming (console)
Você pode testar a instalação de pacotes de instalação por streaming com assinatura de teste de quatro maneiras.Streaming a partir do PC de desenvolvimento
O streaming a partir do PC de desenvolvimento não oferece suporte a nenhuma limitação de taxa de transferência. A velocidade da instalação depende das características de processador e de E/S do seu PC de desenvolvimento, bem como da largura de banda da conexão de rede entre o PC de desenvolvimento e o Kit de Desenvolvimento. Você pode esperar velocidades de 300 Mbps (aproximadamente 36 MiB/s) ou mais em conexões Gigabit Ethernet a partir de PCs de desenvolvimento modernos com discos rígidos mecânicos. xbapp install dev-pc-path-to-XVC Instalar pela linha de comando Instalar pelo XBOX ManagerHospedar o pacote em um servidor Web
Se o seu servidor Web oferecer suporte à configuração de limitação de largura de banda, hospedar o pacote em um servidor Web permite simular diferentes velocidades de entrega pela rede. A plataforma XBOX One lida com falhas de conexão e lógica de repetição. Seu título deve funcionar da mesma forma ao ser instalado a partir de uma fonte da Internet e a partir de um disco óptico, exceto pela velocidade. xbapp install http-URI-to-package Instalar pela linha de comando Instalar pelo XBOX ManagerGravar o pacote em um disco e instalar pela linha de comando
Grave um disco óptico com seu XVC no diretório raiz e, em seguida, instale o pacote usando o comando a seguir. xbapp install XO:\XVC-file-nameGravar o pacote em um disco e instalar pelo shell
Grave um disco óptico com uma pasta chamada MSXC que contenha seu pacote. Insira o disco em um Kit de Desenvolvimento em execução. O shell começa automaticamente a instalar seu título, e o Kit de Desenvolvimento exibe uma notificação depois que o conjunto de inicialização é instalado e o título pode ser iniciado.Práticas recomendadas
Use atualizações de conteúdo em nível de subarquivo
Use atualizações de conteúdo em nível de subarquivo, que reduzem o tamanho das atualizações de conteúdo. Crie o layout do seu pacote de modo a garantir atualizações de conteúdo ideais no futuro. Para obter mais informações sobre como criar pacotes para atualizações ideais, confira Práticas recomendadas de atualização de conteúdo.XBOX Requirement 034 (XR-034: Streaming Install Initial Play Marker)
Incluir um marcador de jogo inicial é opcional, mas altamente recomendado. Ele permite que um usuário execute o título antes que ele esteja completamente instalado, enquanto a instalação continua em segundo plano. De acordo com o XR-034: Streaming Install Initial Player Marker, os títulos que incluem um Initial Play Marker devem fornecer uma experiência de jogo quando iniciados a partir do marcador de jogo inicial.Teste seu título
Teste seu título enquanto ele está sendo instalado a partir de várias fontes e em diferentes velocidades.Use o Submission Validator mais recente
Sempre use a versão mais atualizada do Submission Validator. A versão mais recente do Submission Validator está disponível em XBOX Developer Downloads->XBOX One->Submission Validator.Falhas de empacotamento causadas por conexões de dados abertas
Quando você instala um pacote usandoxbapp install /w, ou quando o XBOX Manager instala um pacote com a opção Keep data connection open habilitada (usada em cenários de Intelligent Delivery e de blocos sob demanda), o canal de dados entre o console e o arquivo de pacote no seu PC permanece aberto após a conclusão da instalação. Essa conexão aberta bloqueia o arquivo de pacote.
Se você tentar recompilar ou reempacotar seu título enquanto esse canal estiver aberto, o makepkg falhará com uma violação de compartilhamento, porque não consegue gravar no arquivo de pacote bloqueado.
Para resolver esse problema, feche a conexão de dados aberta antes de recompilar:
- XBOX Manager: no aplicativo XBOX Manager, localize o pacote instalado e desmarque a opção Keep data connection open, ou desinstale e reinstale o pacote sem essa opção habilitada.
- xbapp install: omita o sinalizador
/wquando não precisar que o canal permaneça aberto após a instalação. Use/wsomente quando seu título precisar solicitar blocos adicionais em tempo de execução durante os testes de desenvolvimento. - Feche o XBOX Manager: fechar completamente o XBOX Manager libera todos os identificadores de arquivo abertos que ele mantém nos arquivos de pacote.
Recursos e orientações
Para obter mais informações, confira os seguintes artigos:- Sistema > Visões gerais > Instalação por streaming e Intelligent Delivery: uma visão geral
- Sistema > Visões gerais > Instalação por streaming > Reordenação dinâmica de blocos
- Sistema > Visões gerais > Instalação por streaming > Instalação por streaming: status
- Teste, automação e publicação > Ferramentas > Instalação por streaming > Esquema do pacote de implantação
- Teste, automação e publicação > Ferramentas > Instalação por streaming > Make Package (makepkg.exe)