ServerDocument.AddCustomization 方法 (String, String, Guid, Uri)

發行項
01/03/2014

使用指定的文件、組件名稱、方案 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
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 所指定的文件有 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。如需詳細資訊，請參閱使用 ClickOnce 部署 Office 方案。

如果指定的文件未包含自訂要求文件所必須具備的控制項，則 AddCustomization 方法會成功，但是當使用者開啟文件時，會無法載入組件。

fileType 參數必須指定具有副檔名的文件，該文件支援 Microsoft Office Word 和 Microsoft 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 或 .NET Framework 4.5)。
  
  或
- 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);
    }
}