런타임 시 VSTO 추가 기능에서 Word 문서 및 Excel 통합 문서 확장

아티클
06/19/2023

VSTO 추가 기능을 사용하여 다음과 같은 방법으로 Word 문서 및 Excel 통합 문서를 사용자 지정할 수 있습니다.

열려 있는 문서 또는 워크시트에 관리되는 컨트롤을 추가합니다.
Excel 워크시트의 기존 목록 개체를 이벤트를 표시하고 Windows Forms 데이터 바인딩 모델을 사용하여 데이터에 바인딩될 수 있는 확장된 ListObject 로 변환합니다.
특정 문서, 통합 문서 및 워크시트에 대해 Word 및 Excel에서 표시하는 애플리케이션 수준 이벤트에 액세스합니다.

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

적용 대상: 이 문서의 정보는 Excel 및 Word의 VSTO 추가 기능 프로젝트에 적용됩니다. 자세한 내용은 Office 애플리케이션 및 프로젝트 형식에 따라 사용 가능한 기능을 참조하세요.

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

확장 개체 는 Visual Studio Tools for Office 런타임에서 제공하는 형식의 인스턴스로, 기본적으로 Word 또는 Excel 개체 모델에 있는 개체( 네이티브 Office 개체라고 함)에 기능을 추가합니다. Word 또는 Excel 개체에 대한 확장 개체를 생성하려면 GetVstoObject 메서드를 사용합니다. 지정된 Word 또는 Excel에 대해 처음으로 GetVstoObject 메서드를 호출하면 지정된 개체를 확장하는 새 개체가 반환됩니다. 메서드를 호출하고 동일한 Word 또는 Excel 개체를 지정할 때마다 동일한 확장 개체가 반환됩니다.

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

GetVstoObject 메서드는 기본적으로 VSTO 추가 기능 프로젝트에서 사용하도록 되어 있습니다. 문서 수준 프로젝트에서 이러한 메서드를 사용할 수도 있지만 다르게 동작하며 더 적게 사용됩니다.

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

호스트 항목 생성

GetVstoObject를 사용하여 문서 수준 개체(즉, Workbook, Worksheet 또는 Document)를 확장하는 경우 반환되는 개체를 호스트 항목이라고 합니다. 호스트 항목은 다른 확장 개체 및 컨트롤을 비롯하여 다른 개체를 포함할 수 있는 형식입니다. 이 형식은 Word 또는 Excel 주 interop 어셈블리의 해당 형식과 유사하지만 추가 기능을 제공합니다. 호스트 항목에 대한 자세한 내용은 호스트 항목 및 호스트 컨트롤 개요를 참조하세요.

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

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

다음 코드 예제에서는 활성 문서에 대한 호스트 항목을 생성하는 방법을 보여 줍니다.

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

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 = _
        Globals.Factory.GetVstoObject(NativeDocument)
End If

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

다음 코드 예제에서는 활성 통합 문서에 대한 호스트 항목을 생성하는 방법을 보여 줍니다.

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

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 =
        Globals.Factory.GetVstoObject(NativeWorkbook)
End If

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

다음 코드 예제에서는 프로젝트의 활성 워크시트에 대한 호스트 항목을 생성하는 방법을 보여 줍니다.

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

Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
    Globals.ThisAddIn.Application.ActiveSheet
If NativeWorksheet IsNot Nothing Then
    Dim vstoSheet As Microsoft.Office.Tools.Excel.Worksheet =
        Globals.Factory.GetVstoObject(NativeWorksheet)
End If

ListObject 호스트 컨트롤 생성

GetVstoObject 메서드를 사용하여 ListObject를 확장하는 경우 메서드는 ListObject를 반환합니다. ListObject에는 원본 ListObject의 모든 기능이 있습니다. 또한 추가 기능이 있으며 Windows Forms 데이터 바인딩 모델을 사용하여 데이터에 바인딩할 수 있습니다. 자세한 내용은 ListObject 컨트롤을 참조하세요.

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

다음 코드 예제에서는 프로젝트의 활성 워크시트에서 첫 번째 ListObject 에 대해 ListObject 를 생성하는 방법을 보여 줍니다.

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

Dim sheet As Microsoft.Office.Interop.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 =
        Globals.Factory.GetVstoObject(listObject)
End If

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

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

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

참고 항목

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

컨트롤 유지 및 제거

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

문서 및 통합 문서에서 애플리케이션 수준 이벤트에 액세스

네이티브 Word 및 Excel 개체 모델에서 일부 문서, 통합 문서 및 워크시트 이벤트는 애플리케이션 수준에서만 발생합니다. 예를 들어 DocumentBeforeSave 이벤트는 Word에서 문서를 열 때 발생하지만 이 이벤트는 Application 클래스가 아닌 Document 클래스에 정의되어 있습니다.

VSTO 추가 기능에서 네이티브 Office 개체만 사용하는 경우 이러한 애플리케이션 수준 이벤트를 처리한 다음 추가 코드를 작성하여 이벤트가 발생한 문서가 사용자 지정한 문서인지를 확인해야 합니다. 호스트 항목은 이러한 이벤트를 문서 수준에서 제공하므로 특정 문서에 대한 이벤트를 더 쉽게 처리할 수 있습니다. 호스트 항목을 생성한 다음 해당 호스트 항목에 대한 이벤트를 처리 할 수 있습니다.

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

다음 코드 예제에서는 Word 문서에 대한 애플리케이션 수준 이벤트를 처리하는 방법을 보여 줍니다. CreateDocument 메서드는 새 문서를 만든 다음 이 문서가 저장되지 않도록 하는 DocumentBeforeSave 이벤트 처리기를 정의합니다. 이벤트는 Application 개체에 대해 발생되는 애플리케이션 수준 이벤트이며 이벤트 처리기는 Doc 매개 변수를 document1 개체와 비교하여 document1가 저장된 문서를 나타내는지 확인해야 합니다.

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;
    }
}

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

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

다음 코드 예제에서는 BeforeSave 호스트 항목의 Document 이벤트를 처리하여 이 프로세스를 간소화합니다. 이러한 예제에서 CreateDocument2 메서드는 Document 개체를 확장하는 document2 를 생성한 다음 문서가 저장되지 않도록 하는 BeforeSave 이벤트 처리기를 정의합니다. 이벤트 처리기는 document2가 저장될 때만 호출되며, 저장된 문서를 확인하는 추가 작업을 수행하지 않고도 저장 작업을 취소할 수 있습니다.

다음 코드 예제에서는 이 작업을 보여 줍니다.

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 = Globals.Factory.GetVstoObject(document2);
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

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

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 = Globals.Factory.GetVstoObject(document2)
End Sub

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

Office 개체가 확장되었는지 확인

확장 개체가 특정 네이티브 Office 개체에 대해 이미 생성되었는지 확인하려면 HasVstoObject 메서드를 사용합니다. 이 메서드는 확장 개체가 이미 생성된 경우 true 를 반환합니다.

Globals.Factory.HasVstoObject 메서드를 사용합니다. 확장 개체에 대해 테스트하려는 네이티브 Word 또는 Excel 개체(예: Document 또는 Worksheet)를 전달합니다.

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

런타임 시 VSTO 추가 기능에서 Word 문서 및 Excel 통합 문서 확장

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

호스트 항목 생성

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

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

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

ListObject 호스트 컨트롤 생성

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

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

컨트롤 유지 및 제거

문서 및 통합 문서에서 애플리케이션 수준 이벤트에 액세스

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

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

Office 개체가 확장되었는지 확인

피드백

피드백

추가 리소스

런타임 시 VSTO 추가 기능에서 Word 문서 및 Excel 통합 문서 확장

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

호스트 항목 생성

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

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

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

ListObject 호스트 컨트롤 생성

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

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

컨트롤 유지 및 제거

문서 및 통합 문서에서 애플리케이션 수준 이벤트에 액세스

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

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

Office 개체가 확장되었는지 확인

관련 콘텐츠

피드백

피드백

추가 리소스