사용자가 선택적으로 생성할 수 있는 지시 XML 파일은 사용자 지정에 따라 패키지가 설치되도록 필요한 지시 정보를 패키지 관리자에 제공합니다.

지시 XML 파일은 여러 하위 요소가 있는 <instructions> 루트 요소로 구성됩니다. 각 하위 요소는 선택 사항입니다.
  • <targetAttributes>
  • <customDirectories>
  • <shortcuts>
  • <returnCodeConventions>
  • <customExecutes>
  • <osUninstallEntry>

지시 XML 파일의 이름을 instructions(으)로 지정하고 파일 확장자를 생략하여 파일 패키지의 data 디렉토리 루트에 둡니다.

다음 텍스트는 파일 패키지 지시 파일의 예입니다. 

<instructions>
    <targetAttributes readOnly="allReadOnly"/>
    <customDirectories>
        <customDirectory name="customDir1" path="D:\subdir"/>
        <customDirectory name="customDir2" path="\\myserver\subdir"/>
    </customDirectories>
    <shortcuts>
        <shortcut>
            <destination root="ProgramMenu" path="Test\Shortcut.lnk">
                <localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" language="de"/>
                <localizedDestination root="ProgramMenu" path="Test\Raccourci.lnk" language="fr"/>
                <localizedDestination root="ProgramMenu" path="Test\ショートカット.lnk" language="ja"/>
                <localizedDestination root="ProgramMenu" path="Test\바로가기.lnk" language="ko"/>
                <localizedDestination root="ProgramMenu" path="Test\快捷方式.lnk" language="zh-CN"/>
            </destination>
            <target root="Program Files" path="Shortcuts\executable.exe"/>
        </shortcut>
    </shortcuts>
    <customExecutes>
        <customExecute root="Documents" exeName="executable.exe"/>
    </customExecutes>
</instructions>

<targetAttributes> 요소

<targetAttributes> 요소는 패키지 관리자가 타겟 시스템에서 파일을 설치하는 위치에 대한 지시 정보를 제공하며, 이 정보는 옵션입니다.

<targetAttributes>는 빈 요소이며, 이는 속성을 포함하지만, 요소나 텍스트 내용은 포함하지 않음을 의미합니다. 포함되는 속성은 다음과 같습니다.

속성 이름 타입 가능한 값 세부사항 예
readOnly 열거형
  • allWritable —원본 소스 파일의 읽기 전용 속성 값과 상관없이 설치에 사용하는 모든 패키지 파일을 쓰기 가능으로 만듭니다.
  • allReadOnly —원본 소스 파일의 읽기 전용 속성 값과 상관없이 설치에 사용하는 모든 패키지 파일을 읽기 전용으로 만듭니다.
  • keepSource —설치 시 원본 소스 파일의 읽기 전용 속성 값을 유지합니다.
    • 모든 파일을 읽기 전용으로 할지, 쓰기 가능으로 할지, 원본 소스 파일의 읽기 전용 속성 값을 유지할지 패키지 관리자에 알립니다.
    • readOnly 속성을 선언하지 않거나, 지시 파일이 없는 경우 기본은 allWritable입니다.
    		<targetAttributes readOnly="allReadOnly"/>

    <customDirectories> 요소

    1 요소는 패키지 관리자가 타겟 시스템에서 파일을 설치하는 절대 경로 위치의 리스트를 제공합니다.

    <customDirectories>는 <customDirectory> 하위 요소를 포함합니다.

    <customDirectory> 요소

    <customDirectory> 요소는 패키지 관리자가 타겟 시스템에서 파일을 설치하는 절대 경로 또는 네트워크 경로를 정의합니다.

    지시 파일에 여러 인스턴스의 <customDirectory>가 있을 수 있습니다.

    속성 이름 타입 값 예
    name 문자열
    Windows 디렉토리 이름에 유효한 문자:
    • 소문자 (a-z), 숫자 (0-9), 더하기 (+) 및 빼기 (-) 기호, 마침표 (.)로만 구성
    • 영숫자로 시작
    • 최소 길이는 2자
    • 최대 길이는 58자
    name 속성은 다음의 경우 에러 발생:
    • 기존 타겟 루트임
    • ni_로 시작됨
    • 유효하지 않은 문자를 포함
    		 <customDirectory name="examplename1" path="D:\bin"/>
    path 문자열 타겟 시스템의 절대 또는 네트워크 경로 <customDirectory name="examplename2" path="\\servername\sharename\subdir"/>

    <shortcuts> 요소

    <shortcuts> 요소는 패키지 관리자가 설치 과정 중에 만드는 바로 가기의 리스트를 제공합니다.

    <shortcuts>는 <shortcut> 하위 요소를 포함합니다.

    <shortcut> 요소

    <shortcut> 요소는 패키지 관리자가 설치 과정 중에 만드는 바로 가기를 정의합니다.

    <shortcut> 요소는 지시 파일에서 선택 사항이지만, 개수의 제한 없이 패키지에 필요한 만큼 포함시킬 수 있습니다. <shortcut>은 두 개의 하위 요소를 포함합니다.
    • <destination>
    • <target>

    <destination> 요소

    <destination> 요소는 패키지 관리자가 바로 가기 파일을 만드는 위치를​지정합니다.

    <destination>은 필수이며 한 개 이상의 선택적 <localizedDestination> 하위 요소를 가질 수 있습니다. 포함되는 속성은 다음과 같습니다.

    속성 이름 타입 값 예
    root 문자열 지원되는 타겟 루트. windows_all 아키텍처가 포함된 패키지는 ProgramFiles_64 또는 LV2017DIR64와(과) 같은 64비트 전용 타겟 루트를 사용할 수 없습니다. <destination root="Startup" path="testShortcut.lnk"/>
    path 문자열 루트 타겟에 추가된 경로 및 파일 이름. 구문 요구사항은 인용 부호에 대한 XML 구문 규칙을 참조하십시오. <destination root="ProgramFiles" path="Shortcuts\test.exe"/>

    <localizedDestination> 요소

    <localizedDestination> 요소는 주어진 언어로 파일 패키지를 설치할 때 바로 가기 파일에 사용할 대체 현지화 경로를 지정합니다.

    <localizedDestination>는 빈 요소이며, 이는 속성을 포함하지만, 요소나 텍스트 내용은 포함하지 않음을 의미합니다. 포함되는 속성은 다음과 같습니다.

    속성 이름 타입 값 예
    root 문자열 지원되는 타겟 루트. windows_all 아키텍처가 포함된 패키지는 ProgramFiles_64 또는 LV2017DIR64와(과) 같은 64비트 전용 타겟 루트를 사용할 수 없습니다. <localizedDestination root="ProgramMenu"/>
    path 문자열 루트 타겟에 추가된 경로 및 파일 이름. <localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" />
    language 문자열

    현지화된 경로의 언어 코드. 가능한 값:

    • de
    • fr
    • ja
    • ko
    • zh-CN
    		<localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" language="de"/>

    <target> 요소

    <target> 요소는 패키지 관리자가 바로 가기를 만드는 파일의 위치를​지정합니다.

    <target>는 빈 요소이며, 이는 속성을 포함하지만, 요소나 텍스트 내용은 포함하지 않음을 의미합니다. 포함되는 속성은 다음과 같습니다.

    속성 이름 타입 값 예
    root 문자열 지원되는 타겟 루트. windows_all 아키텍처가 포함된 패키지는 ProgramFiles_64 또는 LV2017DIR64와(과) 같은 64비트 전용 타겟 루트를 사용할 수 없습니다. <target root="Startup" path="testShortcut.lnk"/>
    path 문자열 루트 타겟이 정해진 후 추가된 경로 및 파일 이름. 구문 요구사항은 인용 부호에 대한 XML 구문 규칙을 참조하십시오. <target root="ProgramFiles" path="Shortcuts\test.exe"/>
    arguments 문자열 타겟 파일에 전달되는 옵션 인수. 구문 요구사항은 인용 부호에 대한 XML 구문 규칙을 참조하십시오. <target root="ProgramFiles" path="Shortcuts\test.exe" arguments="--argument1"/>

    <returnCodeConventions> 요소

    <returnCodeConventions> 요소는 패키지 관리자가 이 패키지에 대해 사용자 정의 작업을 수행할 때 사용할 사용자 정의 반환 코드 형식의 리스트를 제공합니다.

    <returnCodeConventions>는 지시 파일에서 옵션이지만 하나 이상의 <returnCodeConvention> 하위 요소를 포함할 수 있습니다.

    <returnCodeConvention> 요소

    <returnCodeConvention> 요소는 이 패키지에서 하나 이상의 사용자 정의 실행에 대한 반환 코드를 해석하는 방법을 정의합니다.

    <returnCodeConvention>에는 하나 이상의 <returnCode> 하위 요소(옵션)가 있을 수 있습니다. <returnCode> 규칙은 정의된 순서대로 평가됩니다.

    속성 이름 타입 값 예
    name 문자열 이 반환 코드 형식의 고유한 이름. 이 패키지의 사용자 정의 실행은 returnCodeConvention 필드에서 이 이름을 사용하여 이 반환 코드 형식과 연계할 수 있습니다. <returnCodeConvention name="alwaysReboot" defaultResult="rebootRequired"/>
    defaultResult 열거형 기존의 반환 코드 맵핑 규칙과 일치하지 않는 반환 코드의 의미적 결과를 나타냅니다.
    • success
    • failure
    • rebootRequired
    		 <returnCodeConvention name="ignore" defaultResult="success"/>

    <returnCode> 요소

    <returnCode> 요소는 상위 <returnCodeConvention>에 대한 반환 코드 맵핑 규칙을 정의합니다.

    <returnCode>은(는) 빈 요소이며, 이는 속성을 가지고 있지만 요소 또는 텍스트 내용을 포함하지 않음을 의미합니다. 포함되는 속성은 다음과 같습니다.

    속성 이름 타입 값 예
    min 정수 이 규칙과 일치하는 반환 코드 범위의 하위 경계를 나타냅니다. value 속성과 결합할 수 없습니다. <returnCode min="0" max="1024" result="success"/>
    max 정수 이 규칙과 일치하는 반환 코드 범위의 상위 경계를 나타냅니다. value 속성과 결합할 수 없습니다. <returnCode min="-50" max="-1" result="success"/>
    value 정수 이 규칙과 일치하는 단일 반환 코드를 나타냅니다. min 또는 max 속성과 결합할 수 없습니다. <returnCode value="1641" result="rebootRequired"/>
    result 열거형 이 규칙과 일치하는 반환 코드의 의미적 결과를 나타냅니다. <returnCode value="3010" result="rebootRequired"/>

    <customExecutes> 요소

    <customExecutes> 요소는 패키지 관리자가 패키지에 대해 수행할 사용자 지정 작업 리스트를 제공합니다.

    <customExecutes>는 <customExecute> 하위 요소를 포함합니다.

    <customExecute> 요소

    <customExecute> 요소는 패키지 관리자가 패키지에서 수행하는 하나의 사용자 정의 동작을 정의합니다.

    <customExecute> 요소는 지시 파일에서 옵션이지만 패키지에 필요한 만큼 포함시킬 수 있습니다. <customExecute>은(는) 빈 요소이며, 이는 속성을 가지고 있지만 요소 또는 텍스트 내용을 포함하지 않음을 의미합니다. 포함되는 속성은 다음과 같습니다.

    속성 이름 타입 필수 값 설명 예
    root 문자열 예 실행 파일의 루트 경로. windows_all 아키텍처가 포함된 패키지는 ProgramFiles_64 또는 LV2017DIR64와(과) 같은 64비트 전용 타겟 루트를 사용할 수 없습니다. 실행 파일의 루트 경로를 지정합니다.

    지원되는 타겟 루트. 지원되는 타겟 루트를 확인하려면 설치 타겟 루트를 참조하십시오.

    노트 실행 파일을 실행하려면, 우선 실행 파일이 포함된 패키지를 설치해야 합니다. 타겟 루트 경로를 NIPkgMgrTempUnique(으)로 설정하고 schedule 속성을 post(으)로 설정하여 실행 파일을 임시로 설치하도록 패키지를 설정할 수 있습니다. 그러면 패키지 관리자가 패키지를 NIPkgMgrTempUnique 디렉토리에 설치하고, 디렉토리에서 파일을 삭제하기 전에 해당 위치에서 실행 파일을 실행합니다.
    		 <customExecute root="Documents" exeName="executable.exe"/>
    exeName 문자열 예 실행 파일의 경로 및 파일 이름. 실행 파일의 파일 이름을 지정합니다.

    루트에 상대적인 경로를 포함할 수 있습니다. 구문 요구사항은 인용 부호에 대한 XML 구문 규칙을 참조하십시오.

    		 <customExecute root="ProgramData" exeName="actions\executable.exe"/>
    arguments 문자열 아니요 실행 파일로 전달할 명령 라인 인수. 실행 파일로 전달하기 위해 패키지 관리자에 대한 명령 라인 인수를 지정합니다.
    값이 포맷됩니다. 지원되는 타겟 루트 및/또는 다음 인수를 포함시킬 수 있습니다.
    노트 인수는 대소문자를 구분합니다. 구문 요구사항은 인용 부호에 대한 XML 구문 규칙을 참조하십시오.
  • %REBOOTPENDING%—대기 중인 재부팅 정보를 전달합니다. 트랜잭션 종료 시 재부팅이 필요한 경우, 패키지 관리자는 %REBOOTPENDING%을(를) 1로 대체합니다. 필요하지 않으면, 패키지 관리자는 %REBOOTPENDING%을(를) 0으로 대체합니다. schedule 속성의 값이 postall인 경우에만 이 인수를 사용할 수 있습니다.
  • %NIPMLANGUAGECODE%—패키지 관리자가 ISO 언어 코드를 사용할 때 어떤 언어로 실행되는지 지정합니다. 가능한 값: en, de, fr, ko, ja 또는 zh-CN.
    		•
    • <customExecute root="ProgramData" exeName="executable1.exe" arguments="-open %desktop%\file.txt"/>
    • <customExecute root="ProgramData" exeName="executable2.exe" arguments="-reboot %rebootpending%" schedule=postall/>
    • <customExecute root="ProgramData" exeName="executable3.exe" arguments="-language %nipmlanguagecode%"/>
    step 열거형 아니요
  • install —(기본) 패키지 관리자는 패키지를 설치할 때 실행 파일을 실행합니다.
  • uninstall —패키지 관리자는 패키지를 제거할 때 실행 파일을 실행합니다.
  • reinstall —패키지 관리자는 패키지를 복구할 때 실행 파일을 실행합니다.
    		• 패키지 관리자가 실행 파일을 실행하는 트랜잭션 단계를 지정합니다.
    • 설치, 제거, 복구와 같은 여러 단계에서 동일한 실행 파일을 실행하려면 <customExecute> 요소를 각 단계마다 나열합니다.
    • 이 속성을 생략하는 경우, 패키지 관리자는 기본값을 사용합니다.
    노트 패키지를 개발하는 동안 패키지 관리자가 타겟 시스템에서 패키지를 제거할 수 없는 상황을 방지하기 위하여 step 값을 uninstall(으)로 설정하는 경우 ignoreErrors 값을 y(으)로 설정합니다.
    		 <customExecute step="uninstall" root="ProgramData" ignoreErros="y" exeName="actions\executable.exe"/>
    schedule 열거형 아니요
    • post (기본)
    • pre
    • postall
    		패키지 관리자가 실행 파일을 실행하는 시점을 트랜잭션 단계 내의 상대적 시점으로 지정합니다.

    이 속성을 생략하는 경우, 패키지 관리자는 기본값을 사용합니다.

    		 <customExecute step="install" schedule="post" root="ProgramData" exeName="executable.exe"/>
    wait 불리언 아니요
    • n (기본)
    • y
    		사용자 지정 작업이 동기인지 (이때 패키지 관리자는 사용자 지정 작업이 완료될 때까지 기다려야 함), 아니면 비동기인지 (이때 패키지 관리자는 기다리지 않음) 지정합니다.

    이 속성을 생략하는 경우, 패키지 관리자는 기본값을 사용합니다.

    		 <customExecute root="ProgramData" exeName="executable.exe" wait="n"/>
    ignoreErrors 불리언 아니요
    • n (기본)
    • y
    		실행 파일을 실행할 수 없거나 실행 파일이 0이 아닌 값을 반환하는 경우, 패키지 관리자가 에러를 보고할지 지정합니다.
    • 패키지 관리자가 반환 코드를 받을 때까지 기다릴 수 있도록 wait 값을 y(으)로 설정해야 합니다.
    • 이 속성을 생략하는 경우, 패키지 관리자는 기본값을 사용합니다.
    • 이 속성은 ignoreLaunchErrors 또는 returnCodeConvention과 함께 사용할 수 없습니다.
    		 <customExecute root="ProgramData" exeName="executable.exe" wait="y" ignoreErrors="y"/>
    hideConsoleWindow 불리언 아니요
    • n (기본)
    • y
    		콘솔 어플리케이션의 콘솔 윈도우를 숨길지 지정합니다.
    • GUI 어플리케이션을 실행할 때 콘솔 메시지를 표시하지 않습니다.
    • 콘솔 어플리케이션이 실행되긴 하지만, 사용자 입력 또는 메시지 출력을 위한 콘솔 윈도우 없이 실행됩니다.
    • 이 속성을 생략하는 경우, 패키지 관리자는 기본값을 사용합니다.
    • 어플리케이션이 추가로 콘솔 윈도우를 생성할 수 있습니다.
    		 <customExecute root="ProgramData" exeName="executable.exe" hideConsoleWindow="y"/>
    ignoreLaunchErrors 불리언 아니요
    • n (기본)
    • y
    		패키지 관리자가 실행 파일을 찾을 수 없거나 실행할 수 없는 경우, 에러를 보고할지 지정합니다. 이 속성은 ignoreErrors와 함께 사용할 수 없습니다. <customExecute root="ProgramData" exeName="executable.exe" ignoreLaunchErrors="y"/>
    returnCodeConvention 문자열 아니오 이 패키지에 정의된 미리 정의된 형식 또는 <returnCodeConvention> 요소의 이름과 일치해야 합니다. 다음의 미리 정의된 형식을 사용할 수 있습니다.
    • console (기본)
    • installer
    • ignore
    		 실행 파일이 반환하는 반환 코드를 해석하는 방법을 나타냅니다.
    • wait가 y로 설정되어야 하므로 에이전트가 반환 코드를 받을 때까지 기다립니다.
    • console의 경우, 0 = success 및 다른 모든 값은 에러입니다.
    • installer의 경우, 0 = success, 1641 = reboot required, 3010 = reboot required 및 다른 모든 값은 에러입니다.
    • ignore의 경우, 패키지 관리자는 반환 코드를 무시합니다.
    • 이 속성은 ignoreErrors와 함께 사용할 수 없습니다.
    		 <customExecute root="ProgramData" exeName="executable.exe" returnCodeConvention="installer"/>

    Postall로 지정된 실행 파일의 동작

    schedule="postall"인 <customExecute> 요소가 지시 파일에 포함된 경우, 패키지 관리자는 패키지 설치에 영향을 줄 수 있는 특정 동작을 보입니다.

    postall 값은 패키지 관리자가 모든 패키지의 설치, 다시 설치 및/또는 제거 단계를 완료한 후에 실행 파일을 실행하도록 지시합니다.

    • 패키지 관리자는 postall 실행 파일을 지정된 패키지 설치 순서대로 실행합니다. 의존성이 먼저 설치됩니다.
    • 패키지에서 postall 실행 파일만 실행되지 못하는 경우, 패키지 관리자는 패키지가 설치된 것으로 간주합니다.
    • postall 실행 파일이 있는 패키지가 여러 개 있는 경우, postall 실행 파일 중 하나가 실행되지 못하면 패키지 관리자는 나머지 실행 파일을 실행하지 않습니다. 설치 중에 다른 에러가 발생하지 않은 것으로 가정하고, 패키지를 설치된 것으로 간주합니다.
    • MSI 실패, 또는 pre나 post로 지정된 실행 파일의 실패로 패키지가 설치되지 못하는 경우, 패키지 관리자는 패키지 설치 실패를 알리는 에러 메시지를 표시합니다. 그런 다음, 설치 실패 전까지 설치된 패키지의 모든 실행 파일을 실행합니다. 패키지 관리자는 깨진 패키지를 설치된 것으로 간주하지 않으며, 깨진 패키지의 postall 실행 파일을 실행하지 않습니다. 실패가 발생하기 전에 설치된 모든 패키지는 설치된 상태로 남아있고, 패키지 관리자는 이 패키지의 postall 실행 파일을 실행합니다.

    인용 부호에 대한 XML 구문 규칙

    따옴표에 대한 XML 구문 규칙을 검토하여 Microsoft의 조건문 구문을 준수하고 공백이 포함된 경로를 따옴표로 묶도록 합니다.

    Microsoft의 조건문 구문을 준수하려면 리터럴 텍스트를 따옴표 안에 두어야 합니다. 지시 XML 구문은 이 요구사항을 준수하는 두 가지 방법을 제공합니다.

    • 작은 따옴표(')를 사용하여 XML 문자열을 구분합니다. 이렇게 하면 문자열 안에 큰 따옴표를 사용할 수 있습니다. 예를 들면:
      <customExecute condition='IEDETECTED~="Yes" AND VersionNT64 = 601 AND NIRUNNINGINSILENTMODE'/>
    • 큰 따옴표에 XML 이스케이프 문자 &quot;를 사용하여 XML 문자열의 리터럴 텍스트를 구분합니다. XML 이스케이프 문자를 사용하면, 큰 따옴표나 작은 따옴표를 사용하여 XML 문자열을 구분할 수 있습니다. 예를 들면:
      <customExecute condition="IEDETECTED~=&quot;Yes&quot; AND VersionNT64 = 601 AND NIRUNNINGINSILENTMODE"/>

    공백이 포함된 경로는 따옴표로 묶어야 합니다. 작은 따옴표는 경로에 사용할 수 없습니다.

    • 큰 따옴표에 XML 이스케이프 문자 &quot;를 사용하여 XML 문자열에서 경로를 묶습니다. 예를 들면:
      <customExecute exeName="&quot;VC RunTime Installer.exe&quot;" arguments="/q /norestart" inPackage="y"/>

    사용자 지정 실행 예

    다음은 패키지가 설치한 PowerShell 스크립트를 호출하고 설치 후에 두 개의 인수를 전달합니다.

    <customExecute root="BootVolume" exeName="Windows\System32\WindowsPowerShell\v1.0\powershell.exe" arguments="-File &quot;%ProgramData%\My App Name\MyInstallScript.ps1&quot; &quot;argument 1&quot; &quot;argument 2&quot;" step="install" schedule="post" wait="y" ignoreErrors="n" hideConsoleWindow="y" />

    <osUninstallEntry> 요소

    <osUninstallEntry> 요소는 프로그램 추가/제거 인터페이스에 나타나는 패키지에 대해 선택적 지시 정보를 제공합니다.

    <osUninstallEntry>은(는) 빈 요소입니다. 즉, 속성은 있지만 요소나 텍스트 내용은 포함하지 않습니다. <osUninstallEntry>에는 다음과 같은 속성이 있습니다.

    속성 이름 타입 가능한 값 세부사항 예
    ux 열거형
  • ni —(기본) 수정 또는 설치 제거 작업 중 일반적인 패키지 관리자 인터페이스 요소를 표시합니다.
  • oem —수정 또는 설치 제거 작업 중 NI를 참조하는 모든 대화 상자 텍스트와 링크를 숨깁니다.
    		• 타사 패키지의 경우 oem 값은 패키지가 설치된 어플리케이션 리스트에서 first-class 아이템으로 나타나도록 합니다. 수정 및 설치 제거 작업을 수행할 때, 프예로그램 추가/제거 인터페이스는 명명된 패키지만 참조합니다. <osUninstallEntry ux="oem"/>