런타임에 응용 프로그램 수준 추가 기능의 Word 문서 및 Excel 통합 문서 확장

업데이트: 2008년 7월

적용 대상
이 항목의 정보는 지정된 Visual Studio Tools for Office 프로젝트 및 Microsoft Office 버전에만 적용됩니다. 프로젝트 형식 응용 프로그램 수준 프로젝트 Microsoft Office 버전 Excel 2007 Word 2007 자세한 내용은 응용 프로그램 및 프로젝트 형식에 따라 사용 가능한 기능을 참조하십시오.

Visual Studio 2008 SP1(서비스 팩 1)부터는 다음과 같이 응용 프로그램 수준 추가 기능을 사용하여 문서와 통합 문서를 사용자 지정할 수 있습니다.

• 열려 있는 문서 또는 워크시트에 관리되는 컨트롤을 추가합니다.

• 특정 문서 또는 통합 문서에서 인식되는 스마트 태그를 만듭니다.

• 이벤트를 노출하며 Windows Forms 데이터 바인딩 모델을 사용하여 데이터에 바인딩할 수 있는 Visual Studio Tools for Office 목록 개체로 Excel 워크시트의 기존 목록 개체를 변환합니다.

• 특정 문서, 통합 문서 및 워크시트에 대해 Word 및 Excel에서 노출하는 응용 프로그램 수준 이벤트에 액세스합니다.

이 기능을 사용하려면 런타임에 문서 또는 통합 문서를 확장하는 Visual Studio Tools for Office 개체를 생성합니다.

추가 기능에서 확장 개체 생성

확장 개체는 Word 또는 Excel 개체 모델에 기본적으로 포함된 개체(네이티브 Office 개체)에 기능을 추가하는 Visual Studio Tools for Office 개체입니다. 추가 기능에서 확장 개체를 생성하려면 Excel 및 Word 주 interop 어셈블리에서 다음 형식 중 하나의 인스턴스에 대한 GetVstoObject 메서드를 사용합니다.

• Microsoft.Office.Interop.Excel.ListObject

• Microsoft.Office.Interop.Excel.Workbook

• Microsoft.Office.Interop.Excel.Worksheet

• Microsoft.Office.Interop.Word.Document

네이티브 Office 개체의 GetVstoObject 메서드를 처음 호출할 때는 해당 개체를 확장하는 새 Visual Studio Tools for Office 개체가 반환됩니다. 이후에 동일한 네이티브 Office 개체에 대해 이 메서드를 호출하면 항상 동일한 확장 개체가 반환됩니다.

확장 개체의 형식은 네이티브 Office 개체의 형식과 이름은 동일하지만 Microsoft.Office.Tools.Excel 또는 Microsoft.Office.Tools.Word 네임스페이스에 정의되어 있습니다. 예를 들어 Microsoft.Office.Interop.Word.Document 개체의 GetVstoObject 메서드는 Microsoft.Office.Tools.Word.Document를 반환합니다.

특정 네이티브 Office 개체에 대해 Visual Studio Tools for Office 개체가 이미 생성되었는지 여부를 확인하려면 Office 개체의 HasVstoObject 메서드를 사용합니다. 자세한 내용은 Office 개체의 확장 여부 확인을 참조하십시오.

GetVstoObject 메서드는 주로 응용 프로그램 수준 프로젝트에서 사용합니다. 문서 수준 프로젝트에서도 이 메서드를 사용할 수 있지만 이 경우 동작이 달라지며 사용 빈도도 보다 적습니다. 자세한 내용은 문서 수준 사용자 지정의 네이티브 Office 개체에서 확장 개체 가져오기를 참조하십시오.

참고:
ThisAddIn.cs 또는 ThisAddIn.vb 이외의 코드 파일이나 SP1을 설치하기 전에 만든 프로젝트에서 GetVstoObject 및 HasVstoObject 메서드를 사용하려면 프로젝트를 수정해야 합니다. 자세한 내용은 GetVstoObject 및 HasVstoObject 메서드를 사용하도록 프로젝트 구성을 참조하십시오.

호스트 항목 생성

Microsoft.Office.Interop.Excel.Workbook, Microsoft.Office.Interop.Excel.Worksheet 또는 Microsoft.Office.Interop.Word.Document와 같은 문서 수준 개체의 GetVstoObject 메서드를 사용할 때 반환된 개체를 호스트 항목이라고 합니다. 호스트 항목은 다른 확장 개체 및 컨트롤을 비롯하여 다른 개체를 포함할 수 있는 형식입니다. 호스트 항목은 Word 또는 Excel 주 interop 어셈블리의 해당하는 형식과 비슷하지만 추가 기능이 있습니다. 호스트 항목에 대한 자세한 내용은 호스트 항목 및 호스트 컨트롤 개요를 참조하십시오.

호스트 항목을 생성한 후에는 이를 사용하여 문서, 통합 문서 또는 워크시트에 스마트 태그나 관리되는 컨트롤을 추가할 수 있습니다. 자세한 내용은 문서 및 통합 문서에 스마트 태그 추가 및 문서 및 워크시트에 관리되는 컨트롤 추가를 참조하십시오.

Word 문서에 대한 호스트 항목을 생성하려면

• Microsoft.Office.Interop.Word.Document의 GetVstoObject 메서드를 사용합니다. 다음 코드 예제에서는 활성 문서에 대한 호스트 항목을 생성합니다.

  If Globals.ThisAddIn.Application.Documents.Count > 0 Then
      Dim NativeDocument As Microsoft.Office.Interop.Word.Document = _
          Globals.ThisAddIn.Application.ActiveDocument
      Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _
          NativeDocument.GetVstoObject()
  End If
  

  if (Globals.ThisAddIn.Application.Documents.Count > 0)
  {
      Microsoft.Office.Interop.Word.Document nativeDocument =
          Globals.ThisAddIn.Application.ActiveDocument;
      Microsoft.Office.Tools.Word.Document vstoDocument =
          nativeDocument.GetVstoObject();
  }
  

Excel 통합 문서에 대한 호스트 항목을 생성하려면

• Microsoft.Office.Interop.Excel.Workbook의 GetVstoObject 메서드를 사용합니다. 다음 코드 예제에서는 활성 통합 문서에 대한 호스트 항목을 생성합니다.

  Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook = _
      Globals.ThisAddIn.Application.ActiveWorkbook
  
  If NativeWorkbook IsNot Nothing Then
      Dim VstoWorkbook As Microsoft.Office.Tools.Excel.Workbook = _
          NativeWorkbook.GetVstoObject()
  End If
  

  Microsoft.Office.Interop.Excel.Workbook nativeWorkbook =
      Globals.ThisAddIn.Application.ActiveWorkbook;
  
  if (nativeWorkbook != null)
  {
      Microsoft.Office.Tools.Excel.Workbook vstoWorkbook =
          nativeWorkbook.GetVstoObject();
  }
  

Excel 워크시트에 대한 호스트 항목을 생성하려면

• Microsoft.Office.Interop.Excel.Worksheet의 GetVstoObject 메서드를 사용합니다. 다음 코드 예제에서는 활성 워크시트에 대한 호스트 항목을 생성합니다.

  Dim NativeSheet As Microsoft.Office.Interop.Excel.Worksheet = _
      TryCast(Globals.ThisAddIn.Application.ActiveSheet,  _
      Microsoft.Office.Interop.Excel.Worksheet)
  
  If NativeSheet IsNot Nothing Then
      Dim VstoSheet As Microsoft.Office.Tools.Excel.Worksheet = _
          NativeSheet.GetVstoObject()
  End If
  

  Microsoft.Office.Interop.Excel.Worksheet nativeSheet =
      Globals.ThisAddIn.Application.ActiveSheet as
      Microsoft.Office.Interop.Excel.Worksheet;
  
  if (nativeSheet != null)
  {
      Microsoft.Office.Tools.Excel.Worksheet vstoSheet =
          nativeSheet.GetVstoObject();
  }
  

ListObject 호스트 컨트롤 생성

Microsoft.Office.Interop.Excel.ListObject의 GetVstoObject 메서드를 사용하면 Microsoft.Office.Tools.Excel.ListObject가 반환됩니다. 생성된 Microsoft.Office.Tools.Excel.ListObject에는 원본 Microsoft.Office.Interop.Excel.ListObject의 모든 기능이 있으며 Windows Forms 데이터 바인딩 모델을 사용하여 데이터에 바인딩할 수 있는 기능과 같은 추가 기능도 있습니다. 자세한 내용은 ListObject 컨트롤을 참조하십시오.

ListObject에 대한 호스트 컨트롤을 생성하려면

• Microsoft.Office.Interop.Excel.ListObject의 GetVstoObject 메서드를 사용합니다. 다음 코드 예제에서는 활성 워크시트의 첫 번째 Microsoft.Office.Interop.Excel.ListObject에 대한 Microsoft.Office.Tools.Excel.ListObject를 생성합니다.

  Dim sheet As Excel.Worksheet = Globals.ThisAddIn.Application.ActiveSheet
  
  If sheet.ListObjects.Count > 0 Then
      Dim listObject As Excel.ListObject = sheet.ListObjects(1)
      Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject = _
          listObject.GetVstoObject()
  End If
  

  Microsoft.Office.Interop.Excel.Worksheet sheet =
      Globals.ThisAddIn.Application.ActiveSheet as
      Microsoft.Office.Interop.Excel.Worksheet;
  
  if (sheet.ListObjects.Count > 0)
  {
      Excel.ListObject listObject = sheet.ListObjects[1];
      Microsoft.Office.Tools.Excel.ListObject vstoListObject =
          listObject.GetVstoObject();
  }
  

문서 및 통합 문서에 스마트 태그 추가

Microsoft.Office.Tools.Word.Document 또는 Microsoft.Office.Tools.Excel.Workbook을 생성한 후에는 해당 개체가 나타내는 문서 또는 통합 문서의 컨텍스트에서 인식되는 스마트 태그를 만들 수 있습니다. 이렇게 하려면 Microsoft.Office.Tools.Word.Document 또는 Microsoft.Office.Tools.Excel.Workbook의 VstoSmartTags 속성을 사용합니다. 자세한 내용은 다음 항목을 참조하십시오.

• 방법: Word 문서에 스마트 태그 추가

• 방법: Excel 통합 문서에 스마트 태그 추가

문서 및 워크시트에 관리되는 컨트롤 추가

Microsoft.Office.Tools.Word.Document 또는 Microsoft.Office.Tools.Excel.Worksheet를 생성한 후에는 이러한 확장 개체가 나타내는 문서 또는 워크시트에 컨트롤을 추가할 수 있습니다. 이렇게 하려면 Microsoft.Office.Tools.Word.Document 또는 Microsoft.Office.Tools.Excel.Worksheet의 Controls 속성을 사용합니다. 자세한 내용은 런타임에 Office 문서에 컨트롤 추가를 참조하십시오.

Windows Forms 컨트롤이나 호스트 컨트롤을 추가할 수 있습니다. 호스트 컨트롤은 Word 또는 Excel 주 interop 어셈블리의 해당하는 컨트롤을 래핑하는 Visual Studio Tools for Office 컨트롤입니다. 호스트 컨트롤은 기본 네이티브 Office 개체의 모든 동작을 제공하지만 이벤트를 발생시킬 수 있으며 Windows Forms 데이터 바인딩 모델을 사용하여 데이터에 바인딩될 수도 있습니다. 자세한 내용은 호스트 항목 및 호스트 컨트롤 개요를 참조하십시오.

참고:
추가 기능을 사용하여 워크시트에 XmlMappedRange 컨트롤을 추가하거나 문서에 XMLNode 또는 XMLNodes 컨트롤을 추가할 수는 없습니다. 이러한 호스트 컨트롤은 프로그래밍 방식으로 추가할 수 없습니다. 자세한 내용은 호스트 항목 및 호스트 컨트롤의 프로그래밍에 대한 제한 사항을 참조하십시오.

컨트롤 유지 및 제거

문서나 워크시트에 관리되는 컨트롤을 추가할 경우 문서를 저장한 다음 닫을 때는 해당 컨트롤이 유지되지 않습니다. 기본 네이티브 Office 개체만 남도록 모든 호스트 컨트롤은 제거됩니다. 예를 들어 Microsoft.Office.Tools.Excel.ListObject는 Microsoft.Office.Interop.Excel.ListObject가 됩니다. Windows Forms 컨트롤도 모두 제거되지만 이 컨트롤의 ActiveX 래퍼는 문서에 남아 있습니다. 컨트롤을 정리하거나 다음에 문서가 열릴 때 컨트롤을 다시 만들려면 추가 기능에 코드를 포함해야 합니다. 자세한 내용은 Office 문서에서 동적 컨트롤 유지를 참조하십시오.

문서 및 통합 문서의 응용 프로그램 수준 이벤트에 액세스

네이티브 Word 및 Excel 개체 모델의 일부 문서, 통합 문서 및 워크시트 이벤트는 응용 프로그램 수준에서만 발생합니다. 예를 들어 DocumentBeforeSave 이벤트는 Word에서 문서가 열릴 때 발생하지만 이 이벤트가 정의된 클래스는 Microsoft.Office.Interop.Word.Document가 아니라 Microsoft.Office.Interop.Word.Application입니다.

추가 기능에서 네이티브 Office 개체만 사용할 경우 이러한 응용 프로그램 수준 이벤트를 처리한 다음 이벤트가 발생한 문서가 사용자 지정한 문서인지 확인하기 위한 추가 코드를 작성해야 합니다. 호스트 항목은 특정 문서에 대한 이벤트를 보다 쉽게 처리할 수 있도록 문서 수준에서 이러한 이벤트를 제공합니다. 호스트 항목을 생성한 다음 해당 호스트 항목에 대한 이벤트를 처리할 수 있습니다.

네이티브 Word 개체를 사용하는 예제

다음 코드 예제에서는 Word 문서에 대한 응용 프로그램 수준 이벤트를 처리하는 방법을 보여 줍니다. 이 예제의 CreateDocument1 메서드는 새 문서를 만든 다음 이 문서를 저장하지 못하게 하는 DocumentBeforeSave 이벤트 처리기를 정의합니다. 이 이벤트는 Microsoft.Office.Interop.Word.Application 개체에 대해 발생하는 응용 프로그램 수준 이벤트이므로 이벤트 처리기에서는 Doc 매개 변수를 document1 개체와 비교하여 document1이 저장된 문서를 나타내는지 확인해야 합니다.

Private document1 As Word.Document = Nothing

Private Sub CreateDocument1()
    document1 = Me.Application.Documents.Add()
End Sub

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) _
    Handles Application.DocumentBeforeSave
    If Type.ReferenceEquals(Doc, document1) Then
        Cancel = True
    End If
End Sub

private Word.Document document1 = null;

private void CreateDocument1()
{
    document1 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    this.Application.DocumentBeforeSave += 
        new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
        Application_DocumentBeforeSave);
}

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    if (Type.ReferenceEquals(Doc, document1)) 
    {
        Cancel = true;
    }
}

호스트 항목을 사용하는 예제

다음 코드 예제에서는 Microsoft.Office.Tools.Word.Document 호스트 항목의 BeforeSave 이벤트를 처리하여 이 과정을 간단하게 합니다. 이 예제의 CreateDocument2 메서드는 document2 개체를 확장하는 Microsoft.Office.Tools.Word.Document를 생성한 다음 이 문서를 저장하지 못하게 하는 BeforeSave 이벤트 처리기를 정의합니다. 이 이벤트 처리기는 document2가 저장될 때만 호출되므로 저장된 문서를 확인하기 위한 추가 작업을 수행하지 않고 저장 작업을 취소할 수 있습니다.

Private document2 As Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = document2.GetVstoObject()
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object, _
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub

private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;

private void CreateDocument2()
{
    document2 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    vstoDocument = document2.GetVstoObject();
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

Office 개체의 확장 여부 확인

특정 네이티브 Office 개체에 대해 Visual Studio Tools for Office 개체가 이미 생성되었는지 여부를 확인하려면 Office 개체의 HasVstoObject 메서드를 사용합니다. 이 메서드는 확장 개체가 이미 생성되었으면 true를 반환하고, 그렇지 않으면 false를 반환합니다.

확장 여부를 확인하는 것은 지정된 Office 개체에 확장 개체가 있을 때만 코드를 실행하려는 경우에 유용합니다. 예를 들어 DocumentBeforeSave 이벤트를 처리하여 문서가 저장되기 전에 문서에서 관리되는 컨트롤을 제거하는 Word 추가 기능이 있을 경우 HasVstoObject 메서드를 사용하여 문서가 확장되었는지 확인할 수 있습니다. 문서가 확장되지 않은 경우 해당 문서에는 관리되는 컨트롤이 포함될 수 없으므로 이벤트 처리기는 문서의 컨트롤을 정리하려고 시도하지 않고 반환될 수 있습니다.

GetVstoObject 및 HasVstoObject 메서드를 사용하도록 프로젝트 구성

Visual Studio 2008 SP1을 설치한 후 응용 프로그램 수준 프로젝트를 만들면 해당 프로젝트는 ThisAddIn.cs 또는 ThisAddIn.vb 코드 파일에서 GetVstoObject 및 HasVstoObject 메서드를 사용하도록 자동으로 구성됩니다.

ThisAddIn.cs 또는 ThisAddIn.vb 이외의 코드 파일에서 이러한 메서드를 사용하려면 코드 파일을 다음과 같이 변경해야 합니다.

Excel 프로젝트의 코드 파일을 수정하여 확장 개체를 만들려면

• GetVstoObject 및 HasVstoObject 메서드를 사용할 코드 파일의 위쪽에 다음 using(C#의 경우) 또는 Imports(Visual Basic의 경우) 문을 추가합니다.

  Imports Microsoft.Office.Tools.Excel.Extensions
  

  using Microsoft.Office.Tools.Excel.Extensions;
  

Word 프로젝트의 코드 파일을 수정하여 확장 개체를 만들려면

• GetVstoObject 및 HasVstoObject 메서드를 사용할 코드 파일의 위쪽에 다음 using(C#의 경우) 또는 Imports(Visual Basic의 경우) 문을 추가합니다.

  Imports Microsoft.Office.Tools.Excel.Extensions
  

  using Microsoft.Office.Tools.Excel.Extensions;
  

SP1을 설치하기 전에 만든 응용 프로그램 수준 프로젝트에서 이러한 메서드를 사용하려면 프로젝트를 다음과 같이 변경해야 합니다.

기존 Excel 추가 기능을 수정하여 확장 개체를 만들려면

1. Microsoft.Office.Tools.Excel.v9.0.dll 어셈블리에 대한 참조를 추가합니다.

2. GetVstoObject 및 HasVstoObject 메서드를 사용할 코드 파일의 위쪽에 다음 using(C#의 경우) 또는 Imports(Visual Basic의 경우) 문을 추가합니다.

   Imports Microsoft.Office.Tools.Excel.Extensions
   

   using Microsoft.Office.Tools.Excel.Extensions;
   

기존 Word 추가 기능을 수정하여 확장 개체를 만들려면

1. Microsoft.Office.Tools.Word.v9.0.dll 어셈블리에 대한 참조를 추가합니다.

2. GetVstoObject 및 HasVstoObject 메서드를 사용할 코드 파일의 위쪽에 다음 using(C#의 경우) 또는 Imports(Visual Basic의 경우) 문을 추가합니다.

   Imports Microsoft.Office.Tools.Word.Extensions
   

   using Microsoft.Office.Tools.Word.Extensions;
   

이러한 변경 작업은 GetVstoObject 및 HasVstoObject 메서드가 확장 메서드로 구현되기 때문에 필요합니다. GetVstoObject 및 HasVstoObject 메서드는 마치 Excel 또는 Word 주 interop 어셈블리에 정의된 것처럼 사용하지만 실제로는 Visual Studio Tools for Office 런타임의 Microsoft.Office.Tools.Excel.Extensions 및 Microsoft.Office.Tools.Word.Extensions 네임스페이스에 포함된 형식에 정의되어 있습니다. 확장 메서드에 대한 자세한 내용은 확장 메서드(C# 프로그래밍 가이드) 및 확장 메서드(Visual Basic)를 참조하십시오.

참고 항목

작업

Excel 추가 기능 동적 컨트롤 샘플

Word 추가 기능 동적 컨트롤 샘플

개념

응용 프로그램 수준 추가 기능 프로그래밍

런타임에 Office 문서에 컨트롤 추가

호스트 항목 및 호스트 컨트롤 개요

스마트 태그 개요

문서 수준 사용자 지정의 네이티브 Office 개체에서 확장 개체 가져오기

변경 기록

날짜	변경 내용	이유
2008년 7월	항목이 추가되었습니다.	SP1 기능 변경