웹 API 샘플(C#)

게시 날짜: 2017년 1월

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

이 항목에서는 C#을 사용하여 구현하는 웹 API 샘플에 대한 정보를 제공합니다. 각 샘플은 Microsoft Dynamics 365 웹 API의 각기 다른 측면에 초점을 맞추고 있지만 특징 및 구조는 유사합니다.

이 항목의 내용

필수 조건

웹 API 샘플 목록(C#)

샘플을 다운로드하고 실행하는 방법

각 샘플의 일반 요소

필수 조건

Dynamics 365 웹 API C# 샘플을 빌드하고 실행하려면 다음이 필요합니다.

• Microsoft Visual Studio 2015 또는 이상 버전. 무료 버전인 Visual Studio Community은 여기에서 다운로드할 수 있습니다.

• 참조되는 NuGet 패키지를 다운로드하고 업데이트하기 위한 인터넷에 연결.

• Dynamics 365 Online 또는 온-프레미스(또는 이상)에 대한 액세스. Dynamics 365 설치 유형의 경우 CRUD 작업을 수행하는 권한을 가진 사용자 계정이 필요합니다.

• Dynamics 365(온라인)에 대한 예제들을 실행하려면 Azure Active Directory로 응용 프로그램을 등록하여 클라이언트 ID와 리디렉션 URL을 가져와야 합니다. 자세한 내용은 연습: Azure Active Directory를 사용하여 Dynamics 365 등록을 참조하십시오.

웹 API 샘플 목록(C#)

다음 표에서 C#에서 구현하는 샘플을 나열합니다. 여기에서 개괄적으로 설명한 각 샘플은 웹 API 샘플 항목에서 HTTP 요청 및 응답 메시지에 대해 초점을 맞추는 해당 샘플 그룹 항목에 대해 더 자세히 다룹니다.

샘플을 다운로드하고 실행하는 방법

각 샘플에 대한 소스 코드는 MSDN 코드 갤러리에서 사용할 수 있습니다. 이 샘플 항목에는 각 샘플에 대한 다운로드 링크가 포함됩니다. 다운로드 샘플은 샘플에 대한 Visual Studio 2015 솔루션 파일이 포함된 압축된 .zip 파일입니다. 자세한 내용은 각 샘플 항목의 이 샘플 실행 섹션을 참조하십시오.

각 샘플의 일반 요소

일반적으로 웹 API C# 프로그램에 대한 기본 인프라를 제공하기 위해 대부분의 샘플의 구조는 유사하며 일반 메서드 및 리소스를 포함합니다.

이러한 많은 일반적인 요소는 Dynamics 365 웹 API에 액세스할 새로운 솔루션을 만들 때 나타납니다. 자세한 내용은 Visual Studio(C#)에서 Dynamics 365 웹 API 프로젝트 시작을 참조하십시오.

사용되는 라이브러리 및 프레임워크

이 C# 구현은 HTTP 통신, 응용 프로그램 구성, 인증, 오류 처리 및 JSON 직렬화에 대한 다음 도우미 코드에 따라 다릅니다.

• System.Net.Http 네임스페이스(특히 HttpClient, HttpRequestMessage 및 HttpResponseMessage)에 포함된 표준 .NET Framework HTTP 메시징 클래스는 HTTP 메시징을 위해 사용됩니다.

• Dynamics 365 웹 API 도우미 라이브러리는 응용 프로그램 구성 파일 읽기, Dynamics 365 서버 인증, 오류 처리 작업에 사용됩니다. 자세한 내용은 Microsoft Dynamics 365 웹 API 도우미 라이브러리(C#) 사용을 참조하십시오.

• Newtonsoft Json.NET 라이브러리는 JSON 데이터 형식을 지원합니다.

Json.NET 라이브러리

C# 및 다른 대부분의 관리되는 언어는 기본적으로 JSON 데이터 형식을 지원하지 않으므로 현재 가장 좋은 접근 방법은 이 기능에 대한 라이브러리를 사용하는 것입니다. 자세한 내용은 JavaScript 및 .NET에서 JavaScript Object Notation(JSON) 소개. Json.NET은 .NET 프로젝트에 대해 보편적인 선택입니다. JSON 데이터 직렬화, 변환, 구문 분석, 쿼리 및 서식 지정을 위한 강력한 성능과 오픈 소스(MIT 사용이 허가됨) 프레임 워크를 제공합니다. 자세한 내용은 Json.NET 설명서를 참조하십시오.

C# 샘플에서 이 라이브러리는 .NET 개체와 HTTP 메시지 본문 사이의 데이터를 직렬화하기 위해 주로 사용됩니다. 라이브러리에서는 이 작업을 수행하는 데 여러 방법을 제공하지만, 이 샘플에서 사용하는 방법은 개별 JObject 인스턴스를 만들어 Dynamics 365 엔터티 인스턴스(레코드)를 나타내기 위해 사용됩니다. 예를 들어, 다음 코드는 Dynamics 365 contact EntityType 인스턴스를 나타내는 변수 contact1을 만든 다음 이 형식의 선별된 속성 집합에 대한 값을 제공합니다.

JObject contact1 = new JObject();
contact1.Add("firstname", "Peter");
contact1.Add("lastname", "Cambel");
contact1.Add("annualincome", 80000);
contact1["jobtitle"] = "Junior Developer";

마지막 문에서 괄호 표기법은 추가 메서드에 해당합니다. 이 인스턴스화는 구문 분석 정적 메서드를 사용해서도 가능합니다.

JObject contact1 = JObject.Parse(@"{firstname: 'Peter', lastname: 'Cambel', "
+ @"annualincome: 80000, jobtitle: 'Junior Developer'}");

JObject는 일반 JSON 형식을 나타내기 때문에 이를 사용하면 많은 런타임 형식의 검사를 배제합니다. 예를 들어, 다음 문은 구문적으로 유효하지만 contact EntityType에 age 속성이 포함되지 않기 때문에 잠재적으로 런타임 오류로 이어질 수 있습니다.

contact1.Add("age", 37); //Possible error--no age property exists in contact!

엔터티 변수를 초기화한 다음 여러 System.Net.Http 클래스의 도움을 받아 메시지 본문에 보낼 수 있습니다. 예:

HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "contacts");
request.Content = new StringContent(contact1.ToString(), Encoding.UTF8, "application/json");
HttpResponseMessage response = await httpClient.SendAsync(request1);

또한 검색 작업 중 엔터티 인스턴스를 역직렬화하여 JObject 인스턴스를 만들 수도 있습니다. 예:

//contact2Uri contains a reference to an existing CRM contact instance.
string queryOptions = "?$select=fullname,annualincome,jobtitle,description";
HttpResponseMessage response = await httpClient.GetAsync(contact2Uri + queryOptions);
JObject contact2 = JsonConvert.DeserializeObject<JObject>(await response.Content.ReadAsStringAsync());

응답 성공 및 오류 처리

일반적으로 샘플에서는 HTTP 응답을 처리하기 위해 간단한 방법을 사용합니다. 요청이 성공하면 작업에 대한 정보는 일반적으로 콘솔에 출력됩니다. 응답이 JSON 페이로드 또는 유용한 헤더도 전달하면 정보는 성공 시에만 처리됩니다. 마지막으로 Dynamics 365 엔터티를 만든 경우 entityUris 컬렉션은 해당 리소스의 URI로 업데이트됩니다.DeleteRequiredRecords 메서드 메서드가 Dynamics 365 서버의 샘플에서 만든 데이터를 삭제하기 위해 선택적으로 이 컬렉션을 사용합니다.

요청이 실패한 경우 프로그램에서 실패한 작업에 대한 컨텍스트 메시지를 출력한 다음 CrmHttpResponseException 유형의 사용자 지정 예외를 throw합니다. 예외 처리기는 예외에 대한 자세한 정보를 출력하고 컨트롤은 정리 논리를 포함하여 다시 DeleteRequiredRecords에 대한 호출을 포함하여 finally 블록에 전달합니다. 다음 코드에서는 POST 요청으로 레코드를 만드는 이 오류 처리 방법을 설명합니다.

if (response.StatusCode == HttpStatusCode.NoContent)  //204
{
Console.WriteLine("POST succeeded, entity created!”);
//optionally process response message headers or body here, for example:
entityUri = response.Headers.GetValues("OData-EntityId").FirstOrDefault();
entityUris.Add(entityUri);
}
else
{
Console.WriteLine("Operation failed: {0}", response.ReasonPhrase);
throw new CrmHttpResponseException(response.Content);
}

HttpStatusCode.NoContent는 HTTP 상태 코드 204, “콘텐츠 없음”과 같습니다. 여기서 이 상태 코드는 POST 요청이 성공했음을 나타냅니다. 자세한 내용은 HTTP 요청 작성 및 오류 처리를 참조하십시오.

특성 및 메서드

대부분의 샘플에서는 다음과 같은 특징을 가진 같은 일반적인 아키텍처 패턴이 있습니다.

• 모든 관련 C# 샘플 코드는 샘플 프로젝트와 동일한 이름을 가진 단일 클래스를 포함하는 Program.cs라는 이름의 기본 소스 파일에 포함됩니다.

• 샘플 클래스 및 Microsoft Dynamics 365 웹 API 도우미 라이브러리(C#) 사용는 네임스페이스 Microsoft.Crm.Sdk.Samples에 포함됩니다.

• 샘플에는 자유롭게 주석이 달려 있습니다. 요약 정보가 클래스 및 메서드 수준에서 제공되고 대부분의 주요 개별 문은 연결된 같은 주석 또는 한 줄 주석이 있습니다. 응용 프로그램 구성 파일 App.config 등 추가 파일은 종종 중요한 주석을 포함합니다.

• 기본 메서드, ConnectToCRM 메서드, CreateRequiredRecords 메서드, RunAsync 메서드, DisplayException 메서드 및 DeleteRequiredRecords 메서드과 같은 일반 메서드 집합을 포함하도록 기본 샘플 클래스는 일반적으로 구성되어 있습니다.

기본 메서드

기본적으로 이 메서드는 샘플의 실행을 시작합니다. 높은 수준의 제어 흐름 및 예외 처리 논리만을 포함합니다. 보통 정확히 다음의 코드입니다.

static void Main(string[] args)
{
FunctionsAndActions app = new FunctionsAndActions();
try
{
//Read configuration file and connect to specified CRM server.
app.ConnectToCRM(args);
app.CreateRequiredRecords();
Task.WaitAll(Task.Run(async () => await app.RunAsync()));
}
catch (System.Exception ex) { DisplayException(ex);
}
finally
{
if (app.httpClient != null)
{
app.DeleteRequiredRecords(true);
app.httpClient.Dispose();
}
Console.WriteLine("Press <Enter> to exit the program.");
Console.ReadLine();
}
}

ConnectToCRM 메서드

이 메서드는 도우미 라이브러리를 호출하여 응용 프로그램 구성 파일을 읽고 지정된 Dynamics 365 서버로의 연결을 구축합니다. 이러한 단계의 결과로 웹 요청을 보내고 응답을 수신하기 위해 프로그램 전체에서 사용되는 HttpClient 클래스 속성이 초기화됩니다. 이 개체의 속성은 다음과 같이 설정됩니다.

//Define the Web API address, the max period of execute time, the Odata
// version, and the expected response payload format.
httpClient.BaseAddress = new Uri(config.ServiceUrl + "api/data/v8.1/");
httpClient.Timeout = new TimeSpan(0, 2, 0);  // 2 minute timeout
httpClient.DefaultRequestHeaders.Add("OData-MaxVersion", "4.0");
httpClient.DefaultRequestHeaders.Add("OData-Version", "4.0");
httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

샘플 응용 프로그램 구성 및 인증에 대한 자세한 내용은 Microsoft Dynamics 365 웹 API 도우미 라이브러리(C#) 사용을 참조하십시오.

CreateRequiredRecords 메서드

이 작업이 해당 샘플의 초점이 아닌 경우에만 이 메서드로 샘플에서 필요한 엔터티 레코드를 만들고 초기화합니다. 예를 들어, 레코드 생성이 샘플의 주요 고려 사항이 아니기 때문에 해당 웹 API 기본 작업 샘플(C#)은 이 메서드를 포함하지 않습니다.

RunAsync 메서드

이 비동기 메서드는 관련 소스 코드를 포함하거나 더 긴 프로그램의 경우 관련 샘플 코드를 그룹화하는 호출 메서드를 포함합니다. 포함된 코드는 각 해당 샘플 항목의 설명 섹션에 있는 포함된 주석 및 해설에서 설명합니다.

DisplayException 메서드

이 도우미 메서드는 내부 예외를 포함하여 표준 콘솔에 대한 예외 정보를 표시합니다.

DeleteRequiredRecords 메서드

이 도우미 메서드는 필요에 따라 프로그램에서 그리고 특히 CreateRequiredRecords 메서드 메서드로 생성된 샘플 레코드와 기타 Dynamics 365 서버 리소스를 삭제합니다. 이 작업을 확인하기 위해 사용자를 쿼리한 다음 entityUris 컬렉션을 통해 이를 반복하고 HTTP DELETE 메시지를 사용하여 각 요소를 삭제하려고 시도합니다.

참고 항목

Microsoft Dynamics 365 웹 API 사용
웹 API 샘플
웹 API 샘플(클라이언트 쪽 JavaScript)
웹 API 기본 작업 샘플(C#)
웹 API 쿼리 데이터 샘플(C#)
웹 API 조건부 작업 샘플(C#)
웹 API 함수 및 동작 샘플(C#)

Microsoft Dynamics 365

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