사용자 지정 설치 액션

많은 게임은 부정 방지 및 기타 미들웨어를 사용합니다. 이러한 구성 요소는 일반적으로 사용자가 게임을 설치할 때 체인 설치됩니다. 사용자는 어떤 게임은 Microsoft Store를 통해 설치하고, 다른 게임은 다른 배포 채널을 통해 설치할 수 있습니다. 플랫폼은 두 게임이 동일한 미들웨어 패키지를 체인 설치하더라도 충돌이 발생하지 않도록 보장합니다. 게임은 자신의 패키지에 하나 이상의 임의 .exe 또는 .msi 파일을 포함하여, 이 파일들이 앱 설치 완료의 일환으로 실행되도록 요청할 수 있습니다. 사용자 지정 설치 액션 기능은 게임의 부정 방지 소프트웨어 또는 기타 재배포 가능한 미들웨어 설치를 위한 것입니다. 이러한 방식으로, Microsoft Store에 제출된 MSIX 및 다른 배포 채널을 통해 제출된 .msi 또는 .exe 파일에서 정확히 동일한 체인 설치 .exe 파일을 사용할 수 있습니다. 기존 Win32 앱에서 공유 미들웨어는 일반적으로 독립적인 재배포 가능 파일을 통해 설치되며, 이 파일은 일반적으로 자동 압축 해제 .exe 또는 게임 자체와 번들로 제공될 수 있는 .msi 형태를 취합니다. Microsoft Store 앱은 종속성을 게임과 번들로 제공되지 않고 Microsoft Store를 통해 별도로 배포되는 프레임워크 패키지로 모델링합니다. 이 모델에서 소비 앱 매니페스트는 하나 이상의 프레임워크 패키지에 대한 종속성을 선언합니다. 그런 다음 Microsoft Store가 종속성의 체인 설치를 처리합니다. 많은 재배포 가능 파일이 Microsoft Store에서 프레임워크 패키지로 제공되지만, 프레임워크 패키지로 제공되지 않는 일부 재배포 가능 파일이 있을 수밖에 없습니다. 이러한 패키지의 경우 해결책은 게임이 재배포 가능 파일을 게임 패키지 내에 번들로 포함하도록 허용하는 것입니다. .exe 또는 .msi 재배포 가능 파일을 포함하려면 MicrosoftGame.config 파일을 업데이트해야 합니다. 이러한 변경 사항에는 사용하려는 사용자 지정 액션의 유형과 설치 패키지 내에서의 위치를 선언하는 것이 포함됩니다. 모든 재배포 가능 파일은 패키지에 포함되어야 하며 MicrosoftGame.config에 선언되어야 합니다. 이 선언에는 실행 파일의 경로(선언된 Folder 경로에 대한 상대 경로이며, 이 Folder 경로는 다시 패키지 자체의 루트 경로에 대한 상대 경로임)가 포함됩니다. 또한 이 선언에는 실행 파일이 실행될 때 전달될 명령줄 인수도 포함됩니다. 이는 MicrosoftGame.config 파일에 CustomInstallActions 요소를 포함하여 수행됩니다.

CustomInstallActions

CustomInstallActions 요소는 실행될 사용자 지정 설치 액션과 실행 시점에 대한 모든 정의를 포함합니다. MicrosoftGame.config 파일에서 이 요소의 인스턴스는 하나만 선언할 수 있습니다. 필수 자식 요소로 Folder가 있는데, 이는 모든 사용자 지정 액션에 필요한 모든 파일을 포함하는 폴더를 지정하는 문자열입니다. 이 폴더는 하위 폴더를 포함할 수 있습니다. 패키지에 모든 사용자 지정 액션 실행 파일의 종속성이 포함되어 있고, 각각에 대한 적절한 로드 경로에 있는지 확인하는 것은 여러분의 책임입니다.

타이틀을 패키징할 때 makepkg는 이 CustomInstallActions 요소를 생성된 appxmanifest.xml의 MSIX windows.customInstall 확장으로 변환합니다. 그곳에서 동등한 요소는 <CustomInstall>이며, Folder는 특성(attribute) 으로 표현됩니다. 이 <CustomInstall> 형식을 직접 작성하지는 않습니다. MicrosoftGame.config에서 Folder는 이 문서 뒷부분의 게임 config 파일 변경 사항 예제에서 볼 수 있는 것처럼 CustomInstallActions의 자식 요소(element) 입니다.

지정된 Folder에는 주요 게임 실행 파일이나 기타 파일을 넣어서는 안 됩니다. 이 폴더는 오직 사용자 지정 설치 파일 전용입니다.

CustomInstallActions 요소 안에서 앱은 InstallActionList, RepairActionList, UninstallActionList 자식 요소를 선언할 수 있습니다. 이들 모두 선택 사항이며, 이 중 아무거나 선언하거나 아무것도 선언하지 않아도 됩니다. 각 목록 내에서 하나 이상의 InstallAction, RepairAction 또는 UninstallAction 자식 항목을 지정합니다. 플랫폼은 지정한 명령줄 인수와 함께, 지정한 순서로 액션을 실행합니다.

액션 유형

사용자 지정 설치 확장의 세 자식 노드는 특정 사용자 지정 액션이 언제 실행되는지를 결정합니다. 사용자 지정 설치 액션에는 세 가지 유형이 있습니다.

설치 액션(Install action): 앱이 처음 시작되기 전에 플랫폼이 실행하는 액션
복구 액션(Repair action): 사용자가 복구 또는 재설정을 선택할 때 실행되는 액션
제거 액션(Uninstall action): 사용자가 앱을 제거할 때 실행되는 액션

이름과 달리 설치 액션은 패키지가 설치될 때 실행되지 않습니다. 각 액션 유형은 앱 수명 주기의 특정 시점에 실행되며, InstallAction은 타이틀이 처음 실행되기 직전에 한 번 실행됩니다(이는 플랫폼이 필수 UAC 프롬프트를 표시할 수 있는 첫 시점입니다). “Install”, “Repair”, “Uninstall”은 액션이 실행되는 순간이 아니라, 액션이 속한 수명 주기 범주를 이름 짓는 것입니다. 실제 패키지 설치/다운로드 시점에 작업을 수행해야 한다면 사용자 지정 설치 액션은 그 메커니즘이 아닙니다. 전체 시퀀스는 사용자 지정 액션 사용법을 참조하세요.

일반적으로 재배포 가능 파일의 체인 설치를 InstallAction으로 지정한 다음, UninstallAction으로 제거하도록 지정합니다. 그러나 어떤 경우에는 일치하는 제거 없이 설치하도록 선택할 수 있습니다. 이 시나리오에서는 앱이 제거될 때 남아 있는 것을 설치하는 것이며, 다른 앱에서 공유하는 재배포 가능 파일에 적절할 수 있습니다. 마찬가지로 RepairAction은 단순히 InstallAction에 지정한 실행 파일을 다시 선언한 것일 수 있으며, 이것이 일반적입니다. install/repair/uninstall에서 수행하려는 각 액션에 서로 다른 실행 파일이 필요할 수도 있습니다. 스키마는 매우 유연합니다. 플랫폼은 어떤 액션도 요구하지 않습니다. 각 게임에 적절하게 동작을 자유롭게 구성할 수 있습니다.

Uninstall 액션은 Install 또는 Repair 액션이 실행된 경우에만 실행됩니다. 시스템은 이 상태를 추적하기 위해 Name 속성을 사용합니다. 이 때문에 Install/Repair/Uninstall 액션은 동일한 Name을 갖는 것이 중요합니다.

액션의 구성 요소

File

각 액션에 대해 실행할 파일을 지정해야 하며, 이 파일은 패키지에 있어야 합니다. 경로를 지정하면 암시적으로 CustomInstallActions의 Folder 경로에 대한 상대 경로가 됩니다. 절대 경로는 지정할 수 없습니다. 경로는 백슬래시(\)로 시작해서는 안 됩니다.

Name

액션에 대한 Name을 지정해야 합니다. 이 Name은 부모 Actions 노드 내에서 고유해야 하지만, 서로 다른 Actions 노드 간에는 공유될 수 있습니다. 예를 들어 File=“MySetup.exe” 및 Name=“abc123”을 InstallAction과 RepairAction 양쪽에 지정할 수 있습니다. 반면 두 개의 InstallAction 요소가 있는 경우 각각 다른 Name을 가져야 합니다. 해당 실행 파일이 변경되지 않는 한 패키지 버전 전반에 걸쳐 동일한 실행 파일에 대해서는 동일한 Name을 사용해야 합니다. Name은 액션의 정체성으로 사용되며, 플랫폼이 성공적으로 실행된 액션과 업데이트된 패키지에 대해 실행해야 하는 액션을 추적할 수 있게 해줍니다. 업데이트된 패키지가 이미 성공적으로 실행된 Name을 가진 사용자 지정 액션을 지정하면, 플랫폼은 업데이트 시 이 액션을 건너뜁니다.

인수 목록의 차이는 정체성의 차이를 구성하지 않습니다. 업데이트된 패키지에서 동일한 실행 파일을 다른 인수로 실행하려면 다른 Name을 제공해야 합니다. 선언된 Name을 적절하게 구성하고 버전 전반에 걸쳐 추적하는 것은 여러분의 책임입니다.

Arguments

각 사용자 지정 설치 액션에는 세 번째 요소인 arguments가 있어, 재배포 가능 명령을 실행하는 데 필요한 모든 인수를 포함할 수 있습니다.

사용자 지정 액션 사용법

부정 방지 소프트웨어를 설치하려면 일반적으로 사용자에게 관리자 권한이 필요하며, 일반적으로 사용자 지정 액션은 매우 강력한 기능이기 때문에 플랫폼은 사용자 지정 액션이 있는 모든 패키지에 대해 관리자 권한을 요구합니다. 관리자 권한으로 실행되는 작업의 경우, Windows는 앱을 처음 실행할 때 사용자 계정 컨트롤(UAC) 프롬프트를 표시해야 합니다. 사용자 워크플로는 다음과 같습니다.

게임의 Microsoft Store 페이지에는 설치에 상승된 권한이 필요한지, 설치가 사용자 지정 액션을 실행하는지, 이것이 사용자에게 어떤 의미가 있는지를 포함한 요구 사항 설명이 표시됩니다. 이 정보는 사용자가 게임 구매에 대해 정보에 근거한 결정을 내릴 수 있도록 제공됩니다.
사용자가 제약 조건과 그 의미에 만족하면 설치를 선택합니다.
플랫폼은 패키지에 사용자 지정 액션이 포함되어 있음을 감지하고, 사용자 지정 액션을 실행해야 한다는 사실을 기록합니다. 그러나 초기 설치 단계에서는 사용자 지정 액션을 실행하지 않습니다. 대신 사용자 지정 액션은 사용자가 처음 게임을 실행할 때 실행됩니다.
게임을 처음 실행할 때, 플랫폼이 사용자 지정 액션을 실행하려고 하는 시점에 UAC 프롬프트가 표시됩니다. 그런 다음 사용자는 관리자 자격 증명을 제공하고 상승을 수락해야 합니다. 패키지에 여러 사용자 지정 액션이 포함되어 있더라도 사용자에게는 UAC 프롬프트가 한 번만 표시됩니다. 사용자 지정 액션 중 하나 이상이 변경되지 않는 한 업데이트에 대한 추가 UAC 프롬프트는 없습니다. 게임을 제거할 때 UAC 프롬프트가 있습니다.

모든 사용자 지정 액션은 성공에 대해 0을 반환해야 합니다. 사용자 지정 액션이 실패하면 플랫폼은 나머지 사용자 지정 액션을 계속 실행하고 앱을 계속 실행하려고 시도합니다. 이후 앱을 실행할 때마다 플랫폼은 실패한/미완료된 설치 사용자 지정 액션이 성공할 때까지 계속 재시도합니다. 사용자 지정 액션이 실패했을 때 앱이 올바르게 작동하지 않는 경우, 사용자는 언제든 앱의 설정 페이지로 이동하여 복구 또는 재설정을 선택할 수 있습니다. 복구/재설정은 게임 파일을 다시 다운로드하지 않으며, 단순히 패키지를 다시 등록합니다. 실패했거나 실행되지 않은 사용자 지정 액션은 재실행을 위해 다시 등록됩니다. 성공에 대해 0이 아닌 값을 반환하는 사용자 지정 설치 프로그램이 있는 경우, 이 설치 프로그램을 성공 시 0을 반환하는 다른 실행 파일로 감싸는 것이 하나의 옵션입니다. Microsoft Store 정책에는 어떤 종류의 미들웨어/재배포 가능 소프트웨어가 체인 설치될 수 있는지에 대한 지침이 포함되어 있습니다. 상위 수준에서 체인 설치는 게임 실행에 필요한 공유 소프트웨어를 위한 것입니다. 관련 없는 앱이나 기타 소프트웨어를 설치하기 위한 것이 아닙니다.

사용자 지정 설치 액션은 기본 MSIXVC 패키지 내에서만 지원됩니다. 프레임워크 패키지, 선택적 패키지, 수정 패키지 또는 기타 유형의 패키지에서는 지원되지 않습니다.

사용자 지정 설치, 복구, 제거 액션은 소매(retail) Microsoft Store 배포 파이프라인에서 실행됩니다. 개발 목적으로 패키지를 로컬로 설치할 때(예: wdApp install을 사용하여 느슨한 .msixvc를 설치하거나 Add-AppxPackage를 사용하여 패키지를 등록할 때)에는 실행되지 않습니다. 로컬 개발 설치를 사용하면 여전히 패키지가 액션을 올바르게 선언하는지 확인할 수 있지만(생성된 appxmanifest.xml에서 windows.customInstall 확장으로 표시됨), 해당 경로에서는 사용자 지정 액션 실행 파일 자체는 호출되지 않습니다. 액션이 처음부터 끝까지 실행되는 것을 검증하려면 Store 또는 샌드박스 흐름을 통해 타이틀을 설치하세요.

MSI를 사용자 지정 설치 액션으로 실행

MSI의 경우 MSI의 이름을 제공하며, 플랫폼은 해당 파일에 대해 msiexec.exe를 실행합니다. /i, /f 또는 /x 인수는 선언된 액션 유형(install, repair 또는 uninstall)에서 유추되므로 제공하지 마세요. /f 스위치에 대한 옵션은 제공할 수 없습니다. 그러나 일반적으로 msiexec.exe에 제공되는 다른 선택적 인수는 제공할 수 있습니다. 이것이 명령줄 인수가 제한되는 유일한 시나리오입니다. MSI가 아닌 액션의 경우 원하는 인수를 무엇이든 제공할 수 있습니다. MSI가 아닌 액션의 경우 플랫폼은 인수를 구문 분석하거나 검증하지 않습니다. 플랫폼은 단순히 이를 실행 파일에 전달합니다. 인수가 올바른지 확인하는 것은 여러분의 책임입니다. MST(MSI 변환)에 대한 직접적인 지원은 없습니다. MSI/MST에 대한 요구 사항이 있는 경우 가능한 해결 방법 중 하나는 MSI를 실행하고 MST를 적용하기 위해 msiexec를 래핑하는 독립 .exe를 빌드하는 것입니다.

게임 config 파일 변경 사항

다음 XML 예제는 사용자 지정 설치 액션을 허용하기 위해 MicrosoftGame.config 파일에 추가할 적절한 내용을 보여줍니다.

  <!-- Include CustomInstallActions element. Declare InstallActions, 
  RepairActions and/or UninstallActions as appropriate for your app. --> 
  <DesktopRegistration>
    <!-- ... --> 
    <!-- Other entries omitted for brevity. --> 
    <!-- ... --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
        <InstallActionList>
          <InstallAction File="CustomInstaller.exe" Name="TaskName" Arguments="/silent /example" />
        </InstallActionList>
        <RepairActionList>
          <RepairAction File="CustomInstaller.exe" Name="TaskName" Arguments="/silent /repair" />
        </RepairActionList>
        <UninstallActionList>
          <UninstallAction File="CustomInstaller.exe" Name="TaskName" Arguments="/silent /remove" />
        </UninstallActionList>
    </CustomInstallActions>
  </DesktopRegistration>

앞의 예제에서 모든 실행 파일과 종속성은 패키지의 루트에서 지정한 MyInstallers 폴더에 배치해야 합니다. 그 폴더 안에서는 앱에 적합한 어떤 하위 폴더 구조라도 만들 수 있습니다. 이 예제에서 MySetup.exe의 경로는 <package root>\MyInstallers\Banana\MySetup.exe가 됩니다. 해당 실행 파일에 종속성이 있는 경우 이러한 종속성도 적절한 폴더나 하위 폴더에 배치해야 합니다. 다음 시퀀스는 여러 버전에 걸쳐 매니페스트를 어떻게 작성할지를 보여줍니다.

<!-- v1 of the game. --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
      <InstallActionList>
        <InstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /example" />
          <!-- The platform records the successful install of TaskName_1. --> 
      </InstallActionList>
      <RepairActionList>
        <RepairAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /repair" />
      </RepairActionList>
      <UninstallActionList>
        <UninstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /remove" />
        <!-- The platform records the successful uninstall of TaskName_1. --> 
      </UninstallActionList>
    </CustomInstallActions>
      
<!-- v2 of the game, where the redist is NOT updated. --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
        <InstallActionList>
          <InstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /example" />
          <!-- The platform detects that we've already installed TaskName_1, so we don't  
          run it again. Therefore, there's no UAC prompt. --> 
        </InstallActionList>
        <RepairActionList>
          <RepairAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /repair" />
        </RepairActionList>
        <UninstallActionList>
          <UninstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /remove" />
        </UninstallActionList>
      </CustomInstallActions>
 
<!-- v2 of the game, where a redist IS updated. --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
        <InstallActionList>
          <InstallAction File="CustomInstaller.exe" Name="TaskName_2" Arguments="/silent /example" />
          <!-- The platform detects that we haven't previously run TaskName_2, so we need 
          to run it this time and show a UAC prompt. -->  
        </InstallActionList>
        <RepairActionList>
          <RepairAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /repair" />
        </RepairActionList>
        <UninstallActionList>
          <UninstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /remove" />
        </UninstallActionList>
      </CustomInstallActions>

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

CustomInstallActions

액션 유형

액션의 구성 요소

File

Name

Arguments

사용자 지정 액션 사용법

MSI를 사용자 지정 설치 액션으로 실행

게임 config 파일 변경 사항

​CustomInstallActions

​액션 유형

​액션의 구성 요소

​File

​Name

​Arguments

​사용자 지정 액션 사용법

​MSI를 사용자 지정 설치 액션으로 실행

​게임 config 파일 변경 사항

CustomInstallActions

액션 유형

액션의 구성 요소

File

Name

Arguments

사용자 지정 액션 사용법

MSI를 사용자 지정 설치 액션으로 실행

게임 config 파일 변경 사항