ServerDocument.AddCustomization 메서드 (String, String, Guid, Uri)

아티클
08/10/2011

지정된 문서, 어셈블리 이름, 솔루션 ID 및 배포 매니페스트를 사용하여 지정된 문서에 사용자 지정을 연결합니다.

네임스페이스: Microsoft.VisualStudio.Tools.Applications
어셈블리: Microsoft.VisualStudio.Tools.Applications.ServerDocument(Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll)

구문

‘선언
Public Shared Sub AddCustomization ( _
    documentPath As String, _
    assemblyName As String, _
    solutionId As Guid, _
    deploymentManifestUrl As Uri _
)

public static void AddCustomization(
    string documentPath,
    string assemblyName,
    Guid solutionId,
    Uri deploymentManifestUrl
)

매개 변수

documentPath
형식: System.String
사용자 지정을 연결할 문서의 전체 경로입니다.

assemblyName
형식: System.String
사용자 지정에 대한 어셈블리의 전체 경로입니다.이 경로는 로컬 파일 시스템 또는 UNC 공유에 있어야 하며 HTTP 위치는 지정할 수 없습니다.

solutionId
형식: System.Guid
Microsoft Visual Studio Tools for Office Runtime에서 솔루션을 식별하는 데 사용하는 GUID입니다.

deploymentManifestUrl
형식: System.Uri
솔루션의 배포 매니페스트에 대한 URL입니다.

예외

예외	상황
ArgumentNullException	documentPath 또는 assemblyName이 nullNull 참조(Visual Basic의 경우 Nothing)이거나 비어 있는 경우
FileNotFoundException	documentPath 또는 assemblyName에서 존재하지 않는 파일을 참조하는 경우
DocumentAlreadyCustomizedException	documentPath로 지정된 문서에 사용자 지정이 이미 있는 경우
DocumentNotCustomizedException	documentPath로 지정된 문서가 손상되었거나 사용 권한이 제한된 경우
UnknownCustomizationFileException	documentPath로 지정된 문서의 파일 확장명이 Microsoft Visual Studio Tools for Office Runtime에서 지원되지 않는 경우

설명

AddCustomization 메서드는 문서에 _AssemblyName 및 _AssemblyLocation 사용자 지정 문서 속성을 추가하여 지정된 사용자 지정을 문서와 연결합니다. 이러한 속성은 문서에 사용자 지정이 있음을 식별하고 배포 매니페스트의 위치를 지정합니다. 이 메서드가 성공적으로 호출된 후 다음에 사용자가 지정된 문서를 열면 런타임에서 Office 솔루션의 설치를 시도합니다. 사용자 지정 문서 속성에 대한 자세한 내용은 사용자 지정 문서 속성 개요를 참조하십시오.

solutionID 매개 변수에 전달하는 GUID는 문서에 연결할 솔루션의 응용 프로그램 매니페스트에 지정되어 있습니다. 응용 프로그램 매니페스트에 있는 vstov4:document 요소의 solutionId 특성에 지정된 것과 동일한 GUID를 전달해야 합니다. 자세한 내용은 Office 솔루션의 응용 프로그램 및 배포 매니페스트 및 <document> 요소(Visual Studio에서 Office 개발)을 참조하십시오.

게시 위치에서 사용자 지정을 연결하는 경우 assemblyName 매개 변수에 어셈블리의 올바른 파일 이름을 지정해야 합니다. Office 솔루션을 게시할 때 게시 폴더에 복사되는 어셈블리에는 .deploy 파일 확장명이 붙습니다. 예를 들어 어셈블리 이름이 WordDocument1.dll인 경우 게시 폴더에 있는 어셈블리 파일 이름은 WordDocument1.dll.deploy입니다. 자세한 내용은 Office 솔루션 게시을 참조하십시오.

사용자 지정에서 지정된 문서에 있을 것으로 예상하는 컨트롤이 해당 문서에 들어 있지 않은 경우 AddCustomization 메서드가 성공적으로 수행되기는 하지만 사용자가 문서를 열 때 어셈블리가 로드되지 않습니다.

fileType 매개 변수는 Microsoft Office Word 및 Office Excel의 문서 수준 사용자 지정을 지원하는 파일 이름 확장명이 있는 문서를 지정해야 합니다. Word XML 문서(*xml) 또는 Word 2003 XML 문서(*xml) 파일 형식으로 저장되는 문서에 사용자 지정을 첨부할 수 없습니다. 지원되는 파일 형식에 대한 자세한 내용은 문서 수준 사용자 지정 아키텍처를 참조하십시오.

예제

다음 코드 예제에서는 AddCustomization 메서드를 사용하여 지정된 문서에 사용자 지정을 연결합니다.

이 예제에는 다음 사항이 필요합니다.

콘솔 응용 프로그램 프로젝트 또는 다른 비 Office 프로젝트입니다.
다음 어셈블리에 대한 참조:
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll 및 Microsoft.VisualStudio.Tools.Applications.Runtime.dll(.NET Framework 4를 대상으로 하는 프로젝트의 경우)
  
  또는
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll 및 Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll(.NET Framework 3.5를 대상으로 하는 프로젝트의 경우)

Private Sub AddCustomizationUsingAssemblyPath(ByVal documentPath As String, _
    ByVal assemblyName As String, ByVal solutionID As Guid, ByVal deployManifestPath As String)
    Dim runtimeVersion As Integer = 0

    Try
        ' Make sure that this document does not yet have any Visual Studio Tools 
        ' for Office customizations.
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath)
        If runtimeVersion = 0 Then
            Dim deploymentManifestUri As New Uri(deployManifestPath)
            ServerDocument.AddCustomization(documentPath, assemblyName, solutionID, deploymentManifestUri)
            MessageBox.Show("The document was successfully customized.")
        Else
            System.Windows.Forms.MessageBox.Show("The document is already customized.")
        End If

    Catch ex As System.IO.FileNotFoundException
        System.Windows.Forms.MessageBox.Show("The specified document does not exist.")
    Catch ex As UnknownCustomizationFileException
        System.Windows.Forms.MessageBox.Show("The specified document has a file " & _
            "extension that is not supported by Visual Studio Tools for Office.")
    Catch ex As DocumentNotCustomizedException
        System.Windows.Forms.MessageBox.Show("The document could not be customized." & _
        vbLf & ex.Message)
    End Try
End Sub

private void AddCustomizationUsingAssemblyPath(string documentPath, string assemblyName, 
    Guid solutionID, string deployManifestPath)
{
    int runtimeVersion = 0;

    try
    {
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath);

        // Make sure that this document does not yet have any Visual Studio Tools 
        // for Office customizations.
        if (runtimeVersion == 0)
        {
            Uri deploymentManifestUri = new Uri(deployManifestPath);
            ServerDocument.AddCustomization(documentPath, assemblyName, solutionID, deploymentManifestUri);
            MessageBox.Show("The document was successfully customized.");
        }
        else
        {
            System.Windows.Forms.MessageBox.Show("The document is already customized.");
        }
    }
    catch (System.IO.FileNotFoundException)
    {
        System.Windows.Forms.MessageBox.Show("The specified document does not exist.");
    }
    catch (UnknownCustomizationFileException)
    {
        System.Windows.Forms.MessageBox.Show("The specified document has a file " +
            "extension that is not supported by Visual Studio Tools for Office.");
    }
    catch (DocumentNotCustomizedException ex)
    {
        System.Windows.Forms.MessageBox.Show("The document could not be customized.\n" +
            ex.Message);
    }
}