Package Deployer 도구용 패키지 만들기

아티클
06/26/2024

Package Deployer를 사용하여 관리자는 Microsoft Dataverse 인스턴스에 패키지를 배치할 수 있습니다. Package Deployer 패키지는 다음 중 일부 또는 전부로 구성될 수 있습니다.

하나 이상의 Dataverse 솔루션 파일.
플랫 파일 또는 구성 마이그레이션 도구에서 내보낸 구성 데이터 파일입니다. 도구에 대한 자세한 내용은 Configuration Migration Tool을 사용하여 인스턴스 및 조직 간에 구성 데이터 이동을 참조하세요.
Dataverse 인스턴스에 패키지를 배치하기 전에, 동안 또는 후에 실행될 수 있는 맞춤 코드.
배포 프로세스의 시작 및 끝에 표시할 수 있는 패키지에 고유한 HTML 콘텐츠입니다. 본 콘텐츠는 패키지에 배포되는 솔루션 및 파일의 설명을 제공하는 데 유용합니다.

노트

플러그 인 패키지e라는 또 다른 패키지 유형이 있습니다. 이러한 종류의 패키지는 플러그 인 종속 어셈블리용이며 Package Deployer 패키지와 관련이 없습니다.

전제 조건

패키지에 포함하려는 모든 솔루션과 기타 파일이 준비되었는지 확인합니다.
Visual Studio 2019 이후 버전 또는 Visual Studio Code.

프로세스 개요

Package Deployer 패키지를 생성하려면 다음 단계를 수행하십시오.

Visual Studio 또는 MSBuild 프로젝트 만들기
프로젝트에 솔루션 및 기타 파일 추가
제공된 HTML 파일 업데이트(선택 사항)
패키지의 구성 값 지정
패키지에 대한 사용자 지정 코드 정의
패키지 빌드 및 배포

이러한 단계에 대해서는 이 문서에서 자세히 설명합니다.

패키지 프로젝트 만들기

첫 번째 단계는 패키지에 대한 Visual Studio 또는 MSBuild 프로젝트를 만드는 것입니다. 그렇게 하려면 개발 컴퓨터에 사용 가능한 두 가지 도구 확장 중 하나가 설치되어 있어야 합니다. Visual Studio Code를 사용하는 경우 Microsoft Power Platform CLI를 설치하십시오. 그렇지 않고 Visual Studio 2019 이상을 사용하는 경우 Visual Studio용 Power Platform Tools를 설치하세요.

원하는 도구 확장 기능을 사용하여 프로젝트를 생성하는 방법을 알아보려면 아래에서 적절한 탭을 선택하십시오. 두 도구 모두 유사한 형식으로 프로젝트를 출력합니다.

Power Platform CLI
Power Platform 도구

pac package init 명령어를 실행하여 초기 패키지를 생성합니다. 추가 정보: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

결과 CLI 출력에는 아래 표시된 폴더와 파일이 포함됩니다. 여기에서는 "DeploymentPackage" 폴더 이름을 예로 사용했습니다.

C:.
└───DeploymentPackage
    │   DeploymentPackage.csproj
    │   PackageImportExtension.cs
    │
    └───PkgAssets
            ImportConfig.xml
            manifest.ppkg.json

생성된 프로젝트의 PkgAssets 폴더와 PackageImportExtension.cs 파일에서 ImportConfig.xml 구성 파일을 찾습니다. 이 문서의 뒷부분에 설명된 대로 이러한 파일을 수정합니다.

Power Platform 솔루션 템플릿을 사용하여 Visual Studio 프로젝트를 생성하고 나중에 Power Platform 패키지 배포 프로젝트 템플릿을 사용하여 패키지 프로젝트를 추가하거나 Power Platform 패키지 배포 프로젝트 템플릿을 사용하여 직접 프로젝트를 생성할 수 있습니다.

패키지 프로젝트를 추가합니다.

노트

Power Platform 패키지 템플릿을 선택하지 마십시오. 해당 템플릿은 플러그 인 패키지용입니다.

결과 Visual Studio 솔루션 및 프로젝트에는 아래와 같은 폴더와 파일이 포함되어 있습니다. 여기에서는 "Deployment-package" 이름을 예로 사용했습니다. 간결성을 위해 여기에는 Content 폴더의 내용이 표시되지 않습니다.

C:.
│   Deployment-package.csproj
│   Deployment-package.sln
│   GettingStarted.html
│   PackageTemplate.cs
│
├───PkgFolder
│   │   ImportConfig.xml
│   │
│   └───Content

생성된 프로젝트의 PkgFolder 폴더와 PackageTemplate.cs 파일에서 ImportConfig.xml 구성 파일을 찾습니다. 이 문서의 뒷부분에 설명된 대로 이러한 파일을 수정합니다.

Power Platform Tools 확장 사용에 대한 추가 정보: 빠른 시작: Power Platform Tools 프로젝트 만들기

패키지 파일 추가

패키지 프로젝트를 만든 후 해당 프로젝트에 솔루션 및 기타 파일을 추가할 수 있습니다.

Power Platform CLI
Power Platform 도구

CLI를 사용할 때 추가 하위 명령 중 하나를 사용하여 패키지 프로젝트에 외부 패키지, 솔루션 및 참조를 추가할 수 있습니다. 하위 명령 목록을 보려면 pac package help를 입력하십시오. 패키지에 솔루션을 추가해 보겠습니다.

> pac package add-solution help

Commands:
Usage: pac package add-solution --path [--import-order] [--skip-validation] [--publish-workflows-activate-plugins] [--overwrite-unmanaged-customizations] [--import-mode] [--missing-dependency-behavior] [--dependency-overrides]

> cd .\DeploymentPackage\
> pac package add-solution --path ..\TestSolution_1_0_0_1_managed.zip

The item was added successfully.

솔루션 탐색기 창에서 PkgFolder 폴더 아래에 Dataverse 솔루션 및 기타 파일을 추가합니다. HTML 파일은 Content 폴더에 속합니다. 이 HTML 콘텐츠에 대한 자세한 내용은 나중에 설명합니다.
추가하는 각 파일에 대해 속성 창에서 출력 디렉터리로 복사 값을 항상 복사로 설정합니다. 이 값을 설정하면 생성된 패키지에서 파일을 사용할 수 있습니다.

다음으로 HTML 언어 특정 파일을 업데이트합니다.

솔루션 탐색기 창에서 PkgFolder>콘탠츠>en-us를 확장합니다. EndHTML 및 WelcomeHTML이라는 두 폴더를 찾습니다. 이러한 폴더는 패키지 배포 프로세스의 끝과 시작에서 정보를 표시(사용자에게)할 수 있는 HTML 및 관련 파일을 포함하고 있습니다. 이러한 폴더의 HTML 폴더에 있는 파일을 편집하여 패키지에 표시할 정보를 추가하십시오.
또한 HTML에 있는 콘텐츠가 사용자 컴퓨터의 로캘 설정을 기반으로 하는 언어로 나타나도록 다른 언어의 패키지에 있는 HTML 파일을 추가할 수도 있습니다. 수행할 작업:
1. PkgFolder>내용 아래에 en-us 폴더의 사본을 만듭니다.
2. 복사한 폴더의 이름을 적절한 언어로 바꿉니다. 예를 들어, 스페인어의 경우 파일 이름을 es-ES로 바꿉니다.
3. HTML 파일의 콘텐츠를 수정하여 스페인어 콘텐츠를 추가합니다.

패키지 구성

프로젝트의 ImportConfig.xml 파일에 패키지에 대한 정보를 추가하여 패키지 구성을 정의합니다. 사용할 수 있는 유효한 요소와 속성에 대한 예와 설명은 ImportConfig 참조를 참조하세요.

사용자 지정 코드 추가

패키지를 환경으로 가져오기 전, 도중 및 후에 실행하는 사용자 지정 코드를 추가할 수 있습니다. 이렇게 하려면 다음 지침을 따르십시오.

프로젝트의 루트 폴더에서 PackageTemplate.cs(또는 PackageImportExtension.cs) 파일을 편집합니다.

C# 파일에서 다음을 수행할 수 있습니다.

InitializeCustomExtension의 다시 정의 메서드 정의에서 패키지를 정의할 때 실행할 사용자 지정 코드를 입력합니다.

이 매서드 활용하여 사용자가 패키지를 실행하는 동안 런타임 매개 변수를 사용할 수 있습니다. 개발자는 사용자 입력을 기반으로 하는 처리 코드가 있으면 RuntimeSettings 속성을 사용하여 패키지에 대한 런타임 매개 면수 지원을 추가할 수 있습니다.

예를 들어, 다음 샘플 코드는 true 또는 false 두 가지 값을 가질 수 있는 패키지에 대해 SkipChecks라는 런타임 매개 변수를 사용할 수 있게 해 줍니다. 샘플 코드는 사용자가 명령줄 또는 PowerShell을 사용하여 Package Deployer을 실행하는 동안 런타임 매개 변수를 지정했는지 여부를 확인한 다음 이에 따라 정보를 처리합니다. 사용자가 패키지를 실행하는 동안 런타임 매개 변수를 지정하지 않는 경우, RuntimeSettings 속성 값은 null이 됩니다.
```
public override void InitializeCustomExtension()  
{  
// Do nothing.  

// Validate the state of the runtime settings object.  
if (RuntimeSettings != null)  
{  
PackageLog.Log(string.Format("Runtime Settings populated.  Count = {0}", RuntimeSettings.Count));  
foreach (var setting in RuntimeSettings)  
{  
PackageLog.Log(string.Format("Key={0} | Value={1}", setting.Key, setting.Value.ToString()));  
}  

// Check to see if skip checks is present.  
if ( RuntimeSettings.ContainsKey("SkipChecks") )  
{  
bool bSkipChecks = false;  
if (bool.TryParse((string)RuntimeSettings["SkipChecks"], out bSkipChecks))  
OverrideDataImportSafetyChecks = bSkipChecks;  
}  
}  
else  
PackageLog.Log("Runtime Settings not populated");  
}  
```
이 코드를 통해 관리자가 명령줄 또는 Import-CrmPackage cmdlet을 사용하여 패키지를 가져오기 위해 Package Deployer 도구를 실행하는 동안 보안 검사를 건너뛸지 여부를 지정할 수 있습니다. 추가 정보: Package Deployer 및 Windows PowerShell을 사용하여 패키지 배포
PreSolutionImport의 재정의 메서드 정의에 솔루션을 가져오기 전에 실행할 사용자 지정 코드를 입력하여, 대상 Dataverse 인스턴스의 지정된 솔루션을 업데이트하는 동안 사용자 지정을 유지할지 아니면 덮어쓸지 여부와 자동으로 플러그 인 및 워크플로 정품 인증을 실행할지 여부를 지정합니다.

두 버전의 솔루션 간에 데이터 변환 또는 업그레이드를 수행하려면 RunSolutionUpgradeMigrationStep의 대체 메서드 정의를 사용합니다. 이 메서드는 가져오는 솔루션이 대상 Dataverse 인스턴스에 이미 존재하는 경우에만 호출됩니다.

이 함수는 다음 매개 변수가 필요합니다.

매개 변수	설명
`solutionName`	솔루션의 이름
`oldVersion`	기존 솔루션의 버전 번호
`newVersion`	새 솔루션의 버전 번호
`oldSolutionId`	기존 솔루션의 GUID
`newSolutionId`	새 솔루션의 GUID

BeforeImportStage 메서드의 재정의 정의에서 솔루션 가져오기를 완료하기 전에 수행할 사용자 정의 코드를 입력합니다. 솔루션 가져오기를 완료하기 전에 ImportConfig.xml 파일에서 지정된 솔루션에 대한 샘플 데이터 및 몇 가지 플랫 파일을 가져옵니다.
OverrideConfigurationDataFileLanguage의 재정의 메서드 정의를 사용하여 구성 데이터 가져오기에 대해 현재 선택되어 있는 언어를 다시 정의합니다. 특정 언어의 특정 로캘 ID(LCID)가 패키지 내 사용 가능한 언어 목록에 없을 경우, 기본 데이터 파일을 가져옵니다.

ImportConfig.xml 파일의 <cmtdatafiles> 노드에 구성 데이터에 대해 사용 가능한 언어를 정의합니다. ImportConfig.xml 파일의 crmmigdataimportfile 특성에 기본 구성 데이터 가져오기 파일이 정의됩니다.

대상 Dataverse 인스턴스에 아무 데이터도 포함되어 있지 않다고 확신할 경우 여기에서는 데이터 검사 건너뛰기(OverrideDataImportSafetyChecks = true)가 효과적일 수 있습니다.
AfterPrimaryImport> 메서드의 재정의 정의에서 솔루션 가져오기를 완료한 후에 수행할 사용자 정의 코드를 입력합니다. 솔루션 가져오기가 시작되기 전에, 앞서 가져오지 않은 나머지 플랫 파일을 지금 가져옵니다.

패키지 폴더의 기본 이름을 원하는 패키지 이름으로 변경하십시오. 이렇게 하려면 솔루션 탐색기 창에서 PkgFolder(또는 PkgAssets) 폴더의 이름을 바꾼 다음 GetImportPackageDataFolderName 속성에서 반환 값을 편집합니다.

public override string GetImportPackageDataFolderName  
{  
get  
{  
// WARNING this value directly correlates to the folder name in the Solution Explorer where the ImportConfig.xml and sub content is located.  
// Changing this name requires that you also change the correlating name in the Solution Explorer  
return "PkgFolder";  
}  
}

GetNameOfImport 속성 아래에서 반환 값을 편집하여 패키지 이름을 변경합니다.
```
public override string GetNameOfImport(bool plural)  
{  
return "Package Short Name";  
}  
```
이 반환된 값은 Dynamics 365 Package Deployer 마법사의 패키지 선택 페이지에 나타나는 패키지 이름입니다.
GetImportPackageDescriptionText 속성 아래에서 반환 값을 편집하여 패키지 설명을 변경합니다.
```
public override string GetImportPackageDescriptionText  
{  
get { return "Package Description"; }  
}  
```
이 반환된 값은 Package Deployer 마법사의 패키지 선택 페이지에서 패키지 이름과 함께 표시되는 패키지 설명입니다.
GetLongNameOfImport 속성 아래에서 반환 값을 편집하여 패키지 긴 이름을 변경합니다.
```
public override string GetLongNameOfImport  
{  
get { return "Package Long Name"; }  
}  
```
패키지 긴 이름은 설치할 패키지를 선택한 후 다음 페이지에 나타납니다.

또한 다음 함수 및 변수를 패키지에 사용할 수 있습니다.

이름	유형	설명
CreateProgressItem(String)	함수	UI(사용자 인터페이스)의 새로운 진행 중 항목을 만드는 데 사용합니다.
RaiseUpdateEvent(String, ProgressPanelItemStatus)	함수	CreateProgressItem(String)에 대한 호출로 만들어진 진행 상황을 업데이트하는 데 사용됩니다. ProgressPanelItemStatus 다음 값을 갖는 열거형입니다. 작업 중 = 0 완료됨 = 1 실패 = 2 경고 = 3 알 수 없음 = 4
RaiseFailEvent(String, Exception)	Function	예외 메시지와 함께 현재 상태 가져오기에 실패하는 데 사용합니다.
IsRoleAssoicatedWithTeam(Guid, Guid)	함수	역할이 지정된 팀과 연결되어 있는지 확인하는 데 사용합니다.
IsWorkflowActive(Guid)	함수	지정한 워크플로가 활성 상태인지 확인하는 데 사용합니다.
PackageLog	클래스 포인터	패키지를 위해 초기화된 로깅 인터페이스에 대한 포인터입니다. 이 인터페이스는 메시지와 예외를 패키지 로그 파일에 기록하기 위해 패키지에 의해 사용됩니다.
RootControlDispatcher	Property	패키지 배포 중 자체 UI 렌더링을 제어할 수 있도록 활용된 디스패처 인터페이스입니다. 모든 UI 요소 또는 명령을 래핑하기 위해 이 인터페이스를 이용합니다. 값으로 설정할 수 있는지 여부를 알 수 없으므로 사용하기 전에 이 변수에 null 값을 확인하는 것이 중요합니다.
CrmSvc	Property	패키지 내에서 패키지가 Dynamics 365를 다룰 수 있는 CrmServiceClient 클래스에 대한 포인터입니다. 이 포인터를 사용하여 다시 정의된 메서드의 SDK 메서드 및 기타 동작을 실행합니다.
DataImportBypass	Property	Dynamics 365 Package Deployer에서 Dataverse 샘플 데이터, 플랫 파일 데이터 및 구성 마이그레이션 도구에서 내보낸 데이터 같은 모든 데이터 가져오기 작업을 건너뛸지 여부를 지정합니다. true 또는 false를 지정합니다. 기본값은 `false`입니다.
OverrideDataImportSafetyChecks	Property	Dynamics 365 Package Deployer가 일부 안전 검사를 우회하여 가져오기 성능을 향상시키는 데 도움이 되는지 여부를 지정합니다. `true` 또는 `false`를 지정합니다. 기본값은 `false`입니다. 대상 Dataverse 인스턴스에 아무 데이터도 포함되지 않을 경우에는 이 속성을 `true`로 설정해야 합니다.

프로젝트를 저장합니다. 다음 단계는 패키지 빌드입니다.

빌드 및 배포

다음 섹션에서는 패키지를 빌드하고 배포하는 방법을 설명합니다.

빌드

패키지 빌드는 사용 중인 도구에 따라 아래에 설명되어 있습니다.

Power Platform CLI
Power Platform 도구

CLI를 사용하여 생성된 패키지를 빌드하려면 .csproj 파일을 Visual Studio에 로드할 수 있지만 대신 dotnet 명령과 MSBuild를 사용하겠습니다. 아래 예에서는 작업 디렉터리에 *.csproj 파일이 포함되어 있다고 가정합니다.

> dotnet publish

DeploymentPackage -> C:\Users\peter\Downloads\DeploymentPackage\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

선택적으로 빌드된 패키지의 세부 정보를 볼 수 있습니다.

> pac package show --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

패키지는 <Project>\Bin\Debug 폴더 아래에 다음 파일로 구성됩니다.

<패키지 이름> 접는 사람 : 폴더 이름은 이 섹션의 단계 2.g에서 패키지 폴더 이름으로 변경한 것과 동일합니다. 사용자 정의 코드 추가. 이 폴더에는 패키지에 대한 모든 솔루션, 구성 데이터, 플랫 파일 및 콘텐츠가 들어 있습니다.

노트

Pdpublish 폴더가 포함된 .NET 폴더(예: net472)를 볼 수 있습니다. DLL 및 기타 프로젝트 파일은 해당 pdpublish 폴더에 있습니다.

<패키지 이름> .DLL : 어셈블리에는 패키지에 대한 사용자 정의 코드가 포함되어 있습니다. 기본적으로 어셈블리의 이름은 프로젝트 이름과 동일합니다.

배포

패키지를 만든 후 Package Deployer 도구, Windows PowerShell 또는 CLI 명령을 사용하여 Dataverse 인스턴스에 배포할 수 있습니다.

Package Deployer 도구를 사용하여 배포하려면 먼저 Dataverse 개발 도구에 설명된 대로 도구를 다운로드합니다. 그런 다음 Package Deployer 또는 Windows PowerShell을 사용하여 패키지 배포 문서의 패키지 배포에 대한 자세한 정보를 따르세요.
CLI를 사용하여 배포하려면 pac package deploy 명령을 사용합니다.
```
> pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
```
노트

CLI를 사용하여 대상 환경에 패키지를 배포하려면 먼저 인증 프로필을 설정하고 조직을 선택해야 합니다. 추가 정보: pac 인증 만들기, pac 조직 선택

모범 사례

다음은 Package Deployer 패키지로 작업할 때 따라야 할 몇 가지 모범 사례 팁입니다.

패키지 생성

패키지를 생성할 때 개발자는 다음을 수행해야 합니다.

패키지 조립품이 서명되었는지 확인하세요.

패키지 배포

패키지를 배포할 때 Dataverse 관리자는 다음을 수행해야 합니다.

서명된 패키지 조립을 고집하다 이렇게 하면 어셈블리를 출처까지 추적할 수 있습니다.
사전 프로덕션 인스턴스에서 패키지 테스트, 생산 인스턴스 실행하기 전에 생산 인스턴스 미러 이미지가 바람직합니다.
생산 인스턴스 백업 패키지를 배포하기 전에.

참조

솔루션 패키저 도구

다음을 통해 공유