플러그 인 작성

  • 아티클

 

게시 날짜: 2017년 1월

적용 대상: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

플러그 인은 IPlugin 인터페이스를 구현하는 사용자 지정 클래스입니다.Microsoft Visual C# 및 Microsoft Visual Basic .NET과 같은 모든 .NET Framework 4.5.2 CLR 호환 언어로 플러그 인을 작성할 수 있습니다. 플러그 인 코드를 컴파일할 수 있으려면 Microsoft.Xrm.Sdk.dll 및 Microsoft.Crm.Sdk.Proxy.dll 어셈블리 참조를 프로젝트에 추가해야 합니다. 어셈블리는 SDK의 SDK\Bin 폴더에서 찾을 수 있습니다.Microsoft Dynamics CRM SDK 패키지를 다운로드합니다.

이 항목의 내용

플러그 인 디자인

기본 플러그 인 작성

플러그 인 생성자 작성

오프라인 실행 지원

격리된(샌드박스가 적용된) 플러그 인에 대한 웹 액세스

초기 바인딩 유형 사용

플러그 인 어셈블리

플러그 인 디자인

플러그 인 디자인은 Microsoft Dynamics 365(온라인 및 온-프레미스)에 도입된 웹 응용 프로그램 자동 저장 기능을 고려해야 합니다. 자동 저장은 기본적으로 활성화되지만 조직 수준에서 비활성화할 수 있습니다. 자동 저장이 활성화되어 있을 경우 저장 단추가 없습니다. 웹 응용 프로그램은 양식의 데이터를 저장되지 않은 마지막 변경 후 자동으로 30초마다 저장합니다. 양식 수준에서 양식 스크립트를 적용하여 자동 저장 동작을 비활성화할 수 있습니다. 플러그 인을 등록한 방법에 따라 자동 저장은 모든 변경에 대해 하나의 플러그 인을 호출하는 대신 개별 필드 변경에 대해 플러그 인을 더 자주 호출할 수 있습니다.Ctrl+S를 사용하거나, 저장 단추를 누르거나, 자동 저장 기능으로 자동으로 수행되는지에 상관 없이 언제든지 모든 사용자가 모든 레코드를 저장할 수 있다고 가정합니다.

가장 중요한 엔터티 및 특정 필드에서 플러그 인 또는 워크플로를 등록하는 효과적인 방법입니다. 모든 엔터티 필드에 대한 변경에 대해 플러그 인 또는 워크플로를 등록하지 않는 것이 좋습니다. 자동 저장 기능을 사용할 수 있기 전에 구현된 기존 플러그 인 또는 워크플로가 있을 경우 제대로 작동하는지 확인하기 위해 해당 코드를 다시 테스트해야 합니다. 자세한 내용은 TechNet: 자동 저장 관리를 참조하십시오.

기본 플러그 인 작성

다음 샘플에서는 플러그 인에 있는 일반적인 코드 중 일부를 보여 줍니다. 이 샘플의 경우 코드는 플러그 인의 계획된 작업을 수행하는 사용자 지정 비즈니스 논리를 생략합니다. 하지만 코드는 IPlugin 인터페이스와 필수 Execute 메서드를 구현하는 플러그 인 클래스를 보여 줍니다.

using System;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;

public class MyPlugin: IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // Extract the tracing service for use in debugging sandboxed plug-ins.
        // If you are not registering the plug-in in the sandbox, then you do
        // not have to add any tracing service related code.
        ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

        // Obtain the execution context from the service provider.
        IPluginExecutionContext context = (IPluginExecutionContext)
            serviceProvider.GetService(typeof(IPluginExecutionContext));

        // The InputParameters collection contains all the data passed in the message request.
        if (context.InputParameters.Contains("Target") &&
            context.InputParameters["Target"] is Entity)
        {
            // Obtain the target entity from the input parameters.
            Entity entity = (Entity)context.InputParameters["Target"];

            // Verify that the target entity represents an entity type you are expecting. 
            // For example, an account. If not, the plug-in was not registered correctly.
            if (entity.LogicalName != "account")
                return;

            // Obtain the organization service reference which you will need for
            // web service calls.
            IOrganizationServiceFactory serviceFactory = 
                (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
            IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

            try
            {
                // Plug-in business logic goes here.
            }

            catch (FaultException<OrganizationServiceFault> ex)
            {
                throw new InvalidPluginExecutionException("An error occurred in MyPlug-in.", ex);
            }

            catch (Exception ex)
            {
                tracingService.Trace("MyPlugin: {0}", ex.ToString());
                throw;
            }
        }
    }
}

Execute 메서드의 IServiceProvider 매개 변수는 플러그 인 안에서 액세스할 수 있는 몇 가지 서비스 유용한 개체에 대한 컨테이너입니다. 서비스 공급자에는 실행 컨텍스트에 대한 인스턴스 참조(IOrganizationServiceFactory, ITracingService 등)가 들어 있습니다. 샘플 코드는 실행 컨텍스트에 대한 참조 IOrganizationService와 ITracingService를 서비스 공급자 매개 변수에서 가져오는 방법을 보여 줍니다. 추적 서비스에 대한 자세한 내용은 플러그 인 디버깅를 참조하십시오.

실행 컨텍스트에는 플러그 인을 실행하도록 하는 이벤트와 현재 파이프라인에서 처리 중인 메시지에 포함된 데이터에 대한 다양한 정보가 들어 있습니다. 데이터 컨텍스트에 대한 자세한 내용은 플러그 인에 전달된 데이터 컨텍스트 이해를 참조하십시오.

플랫폼은 서비스 공급자에서 조직 웹 서비스 참조를 가져올 때 올바른 웹 서비스 URL과 네트워크 자격 증명을 제공 합니다. 웹 서비스 프록시는 교착 상태 및 인증 문제를 생성하므로 인스턴스화할 수 없습니다. 조직에 서비스 참조를 설정한 후 이를 사용하여 조직 웹 서비스에 대해 메서드 호출을 할 수 있습니다. 웹 서비스에 대한 하나 이상의 메시지 요청을 발급하여 단일 Microsoft Dynamics 365 조직의 비즈니스 데이터를 검색하거나 변경할 수 있습니다. 메시지 요청에 대한 자세한 내용은 Execute 메서드와 함께 메시지(요청 및 응답 클래스) 사용을 참조하십시오.

일반적인 플러그 인은 컨텍스트에서 정보에 액세스하고, 요청된 비즈니스 작업을 수행하고, 예외를 처리해야 합니다. 플러그 인에서 예외를 처리하는 방법에 대한 자세한 내용은 플러그 인의 예외 처리를 참조하십시오. 기타 전체 플러그 인 샘플은 샘플: 기본 플러그인 만들기 항목에서 사용할 수 있습니다.

중요

향상된 성능을 위해 Microsoft Dynamics 365에서는 플러그 인 인스턴스를 캐시합니다. 플러그 인의 Execute 메서드는 생성자가 플러그 인을 호출할 때마다 호출되지 않으므로 상태 없이 작성되어야 합니다. 다중 시스템 스레드는 동시에 플러그 인을 실행할 수도 있습니다. 호출 상태 정보는 모두 컨텍스트에 저장되므로 전역 변수를 사용하거나 데이터가 생성자에 제공된 구성 매개 변수에서 가져온 것이 아니면 다음 플러그 인 호출 중 사용하기 위해 멤버 변수에 해당 데이터를 저장하지 않아야 합니다. 플러그 인 등록을 변경하면 플러그 인이 다시 초기화됩니다.

플러그 인 생성자 작성

Microsoft Dynamics 365 플랫폼은 하나 또는 두 개의 문자열 매개 변수를 허용하는 선택적인 플러그 인 생성자를 지원합니다. 다음과 같이 생성자를 작성하면 런타임에 모든 정보 문자열을 플러그 인에 전달할 수 있습니다.

다음 샘플에서는 생성자의 형식을 보여 줍니다. 이 예제에서 플러그 인 클래스의 이름은 SamplePlugin입니다.

public SamplePlugin()
public SamplePlugin(string unsecure)
public SamplePlugin(string unsecure, string secure)

생성자의 첫 번째 문자열 매개 변수에는 공개(비보안) 정보가 들어 있습니다. 두 번째 문자열 매개 변수에는 비공개(보안) 정보가 들어 있습니다. 이 설명에서 비보안은 암호화되지 않은 값이며 보안은 암호화 된 값을 말합니다.Microsoft Office Outlook용 Microsoft Dynamics 365(오프라인 액세스 가능)를 사용할 경우 보안 문자열은 Outlook용 Dynamics 365이 오프라인 상태에서 실행되는 플러그 인에 전달되지 않습니다.

이러한 문자열에서 플러그 인 생성자에 전달되는 정보는 플러그 인이 Microsoft Dynamics 365에 등록될 때 지정됩니다. 플러그 인 등록 도구를 사용하여 플러그 인을 등록할 경우 새 단계 등록 양식에 제공되는 보안 구성 및 비보안 구성 필드에 안전한 정보와 안전하지 않은 정보를 입력할 수 있습니다.Microsoft Dynamics 365 SDK를 사용하여 플러그 인을 프로그래밍 방식으로 등록할 경우 SdkMessageProcessingStep.Configuration에는 안전하지 않은 값이 포함되고 SdkMessageProcessingStep.SecureConfigId는 안전한 값이 있는 SdkMessageProcessingStepSecureConfig 레코드를 참조합니다.

오프라인 실행 지원

플러그 인을 온라인 모드, 오프라인 모드 또는 둘 다에서 실행하도록 등록할 수 있습니다. 오프라인 모드는 Microsoft Office Outlook용 Microsoft Dynamics 365(오프라인 액세스 가능)에서만 지원됩니다. 플러그 인 코드는 IsExecutingOffline 속성을 확인하여 오프라인 모드에서 실행되는지 여부를 확인할 수 있습니다.

온라인 및 오프라인 모두에서 실행되도록 등록되는 플러그 인을 디자인할 때 플러그 인을 두 번 실행할 수 있습니다. 첫 번째는 Microsoft Office Outlook용 Microsoft Dynamics 365(오프라인 액세스 가능)이 오프라인인 동안입니다. 플러그 인은 Outlook용 Dynamics 365이 온라인으로 전환되고 Outlook용 Dynamics 365과 Microsoft Dynamics 365 서버 간 동기화가 일어날 때 다시 실행됩니다.IsOfflinePlayback 속성을 확인하여 이 동기화로 인해 플러그 인이 실행되는지 여부를 확인할 수 있습니다.

격리된(샌드박스가 적용된) 플러그 인에 대한 웹 액세스

샌드박스에서 플러그 인을 등록하려는 경우 플러그 인 코드에서 웹 주소에 계속 액세스할 수 있습니다.플러그 인 격리, 트러스트 및 통계에 요약되어 있는 웹 액세스 제한 내에서 웹 액세스를 제공하는 플러그 인 코드에서 모든 .NET Framework 클래스를 사용할 수 있습니다. 예를 들어 다음 플러그 인 코드는 웹 페이지를 다운로드합니다.


// Download the target URI using a Web client. Any .NET class that uses the
// HTTP or HTTPS protocols and a DNS lookup should work.
using (WebClient client = new WebClient())
{
    byte[] responseBytes = client.DownloadData(webAddress);
    string response = Encoding.UTF8.GetString(responseBytes);
System_CAPS_security 보안 참고

외부 웹 서비스에 액세스할 수 있는 샌드박스가 적용된 플러그 인의 경우 샌드박스 처리 서비스 역할이 설치되어 있는 서버가 인터넷에 노출되어야 하고 샌드박스 서비스가 실행되는 계정에 인터넷 액세스 권한이 있어야 합니다. 포트 80 및 443에서 아웃바운드 연결만 필요합니다. 인바운드 연결 액세스는 필요하지 않습니다. Windows 방화벽 제어판을 사용하여 %PROGRAMFILES%\Microsoft Dynamics 365\Server\bin 폴더에서 서버에 있는 Microsoft.Crm.Sandbox.WorkerProcess 응용 프로그램에 대한 아웃바운드 연결을 활성화합니다.

초기 바인딩 유형 사용

플러그 인 코드에서 초기 바인딩 Microsoft Dynamics 365 유형을 사용하려면 Microsoft Visual Studio 플러그 인 프로젝트에서 CrmSvcUtil 프로그램을 사용하여 생성된 유형 파일을 포함하면 됩니다.

런타임에 바인딩된 엔터티의 초기 바인딩된 엔터티로의 변환은 다음과 같이 처리됩니다.

Account acct = entity.ToEntity<Account>();

앞의 코드 줄에서 acct 변수는 초기 바인딩 유형입니다.IPluginExecutionContext에 할당되는 모든 Entity 값은 런타임에 바인딩 유형이어야 합니다. 초기 바인딩 유형이 컨텍스트에 할당되면 SerializationException이 발생합니다. 자세한 내용은 플러그 인에 전달된 데이터 컨텍스트 이해을 참조하십시오. 다음 코드와 같이 런타임에 바인딩 유형이 호출되면 유형을 혼합하지 않고 초기 바인딩 유형을 사용해야 합니다.

context.InputParameters["Target"] = new Account() { Name = "MyAccount" }; // WRONG: Do not do this.

위의 예제에서 런타임에 바인딩된 인스턴스를 저장해야 하는 플러그 인 컨텍스트에 초기 바인딩된 인스턴스를 저장하지 않습니다. 이는 플러그 인을 호출하기 전에 그리고 플러그 인에서 플랫폼으로 반환할 때 초기 바인딩 유형과 런타임에 바인딩 유형 간 플랫폼을 변환하지 않도록 하기 위해서입니다.

플러그 인 어셈블리

어셈블리에 하나 이상의 플러그 인 유형이 있을 수 있습니다. 플러그 인 어셈블리가 등록되고 배포된 후 플러그 인은 Microsoft Dynamics 365 런타임 이벤트에 대한 응답으로 원하는 작업을 수행할 수 있습니다.

System_CAPS_security 보안 참고

Microsoft Dynamics 365에서 플러그 인 어셈블리는 제대로 작동하려면 모든 사용자가 읽을 수 있어야 합니다. 따라서 시스템 로그온 정보, 기밀 정보 또는 회사 영업 비밀이 포함되지 않은 플러그 인 코드를 개발하는 보안상 가장 좋은 방법입니다.

각 플러그 인 어셈블리는 Microsoft Dynamics 365에 등록하고 배포하기 전에 Microsoft Visual Studio에서 프로젝트의 속성 시트의 서명 탭을 사용하거나 강력한 이름 도구를 사용하여 서명해야 합니다. 강력한 이름 도구에 대한 자세한 내용을 보려면 Microsoft Visual Studio 명령 프롬프트 창에서 다른 인수 없이 sn.exe 프로그램을 실행하십시오.

어셈블리에 Outlook용 Dynamics 365이 오프라인 상태에서 실행할 수 있는 플러그 인이 있을 경우 Microsoft Dynamics 365 플랫폼에서 어셈블리에 적용하는 추가 보안이 있습니다. 자세한 내용은 연습: 오프라인 플러그 인에 대해 어셈블리 보안 구성을 참조하십시오.

참고 항목

플러그 인 개발
플러그 인에 전달된 데이터 컨텍스트 이해
사용자 지정 Azure 인식 플러그 인 작성
플러그 인 등록 및 배포
플러그 인의 예외 처리
샘플: 기본 플러그인 만들기
샘플: 샌드박스가 적용된 플러그 인에서 웹 액세스
코드 생성 도구 실행
블로그: 플러그 인을 사용하여 보기 수정

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. 저작권 정보