ServerDocument.AddCustomization Метод

Определение

Перегрузки

AddCustomization(String, Uri)

Прикрепляет настройку к указанному документу с помощью заданного имени и манифеста развертывания.Attaches a customization to the specified document by using the specified assembly name and deployment manifest.

AddCustomization(String, String, Guid, Uri)

Вкладывает настройку в указанный документ, используя указанный документ, имя сборки, идентификатор решения и манифест развертывания.Attaches a customization to the specified document by using the specified document, assembly name, solution ID, and deployment manifest.

AddCustomization(String, String, Guid, Uri, Boolean, String[])

AddCustomization(String, Uri)

Прикрепляет настройку к указанному документу с помощью заданного имени и манифеста развертывания.Attaches a customization to the specified document by using the specified assembly name and deployment manifest.

public static void AddCustomization (string documentPath, Uri deploymentManifestUrl);

Параметры

documentPath
String

Полный путь к документу, в который необходимо вложить настройку.The full path of the document to which you want to attach a customization.

deploymentManifestUrl
Uri

URL-адрес манифеста развертывания для решения.The URL of the deployment manifest for the solution.

Исключения

Параметр documentPath или deploymentManifestUrl имеет значение null или пуст.documentPath or deploymentManifestUrl is null or empty.

В параметре deploymentManifestUrl не указан абсолютный URL-адрес.deploymentManifestUrl does not specify an absolute URL.

documentPath или deploymentManifestUrl ссылается на несуществующий файл.documentPath or deploymentManifestUrl refers to a file that does not exist.

Документ, заданный параметром documentPath, уже содержит настройку.The document specified by documentPath already has a customization.

Манифеста развертывания, указанный в параметре deploymentManifestUrl, не является действительным манифестом развертывания.The deployment manifest specified by deploymentManifestUrl is not a valid deployment manifest.

Документ, заданный параметром documentPath, поврежден или имеет ограниченные разрешения.The document specified by documentPath is corrupt, or has restricted permissions.

Документ, заданный параметром documentPath, имеет расширение имени файла, которое не поддерживается Набор средств Visual Studio для Office (cреда выполнения)Visual Studio Tools for Office runtime.The document specified by documentPath has a file name extension that is not supported by the Набор средств Visual Studio для Office (cреда выполнения)Visual Studio Tools for Office runtime.

Примеры

В следующем примере кода метод используется AddCustomization для присоединения настройки к указанному документу.The following code example uses the AddCustomization method to attach a customization to the specified document.

Для этого примера требуются:This example requires:

  • Проект консольного приложения или другой проект, не относящийся к Office.A console application project or some other non-Office project.

  • Ссылки на следующие сборки:References to the following assemblies:

    • Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll и Microsoft.VisualStudio.Tools.Applications.Runtime.dll (если проект предназначен для платформы .NET Framework 4.NET Framework 4 или .NET Framework 4.5.NET Framework 4.5).Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll and Microsoft.VisualStudio.Tools.Applications.Runtime.dll (if the project targets the .NET Framework 4.NET Framework 4 or the .NET Framework 4.5.NET Framework 4.5).

      oror

    • Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll и Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll (если проект предназначен для .NET Framework 3,5).Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll and Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll (if the project targets the .NET Framework 3.5).

  • Imports(для Visual Basic) или using (для C#) для Microsoft.VisualStudio.Tools.Applications Microsoft.VisualStudio.Tools.Applications.Runtime пространств имен и в верхней части файла кода.Imports (for Visual Basic) or using (for C#) statements for Microsoft.VisualStudio.Tools.Applications and Microsoft.VisualStudio.Tools.Applications.Runtime namespaces at the top of your code file.

private void AddCustomizationUsingDocumentPath(string documentPath, 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, 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);
    }
}
Private Sub AddCustomizationUsingDocumentPath(ByVal documentPath As String, _
    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, 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

Комментарии

AddCustomizationМетод связывает указанную настройку с документом, добавляя к _AssemblyName _AssemblyLocation документу и пользовательские свойства документа.The AddCustomization method associates the specified customization with the document by adding the _AssemblyName and _AssemblyLocation custom document properties to the document. Эти свойства определяют, что документ имеет настройку, и указывает расположение манифеста развертывания.These properties identify that the document has a customization and specify the location of the deployment manifest. После того как этот метод будет успешно вызван, при следующем открытии пользователем указанного документа среда выполнения попытается установить решение Office.After this method is successfully called, the next time a user opens the specified document, the runtime will attempt to install the Office solution. Дополнительные сведения о настраиваемых свойствах документа см. в разделе Общие сведения о пользовательских свойствахдокумента.For more information about the custom document properties, see Custom Document Properties Overview.

Если указанный документ не содержит элемент управления, который требуется для документа настройки, AddCustomization метод будет успешным, но сборка не будет загружена, когда пользователь откроет документ.If the specified document does not contain a control that the customization expects the document to have, the AddCustomization method will succeed, but the assembly will fail to load when the user opens the document.

fileTypeПараметр должен указывать документ с расширением имени файла, который поддерживается для настроек на уровне документа.The fileType parameter must specify a document that has a file name extension that is supported for document-level customizations. Невозможно присоединить настройку к документу, сохраненному в форматах XML-документов Word (* XML) или Word 2003 * .You cannot attach a customization to a document that is saved in the Word XML Document (*xml) or Word 2003 XML Document (*xml) file formats. Дополнительные сведения о поддерживаемых типах файлов см. в разделе Архитектура настроек на уровне документа.For more information about the supported file types, see Architecture of Document-Level Customizations.

Применяется к

AddCustomization(String, String, Guid, Uri)

Вкладывает настройку в указанный документ, используя указанный документ, имя сборки, идентификатор решения и манифест развертывания.Attaches a customization to the specified document by using the specified document, assembly name, solution ID, and deployment manifest.

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

Параметры

documentPath
String

Полный путь к документу, в который необходимо вложить настройку.The full path of the document to which you want to attach a customization.

assemblyName
String

Полный путь к сборке для настройки.The full path of the assembly for the customization. Путь должен вести к папке в локальной файловой системе или к общей UNC-папке; нельзя указывать расположение HTTP.The path must be on the local file system or a UNC share; you cannot specify an HTTP location.

solutionId
Guid

GUID, используемый Набор средств Visual Studio для Office (cреда выполнения)Visual Studio Tools for Office runtime для идентификации решения.A GUID that the Набор средств Visual Studio для Office (cреда выполнения)Visual Studio Tools for Office runtime uses to identify the solution.

deploymentManifestUrl
Uri

URL-адрес манифеста развертывания для решения.The URL of the deployment manifest for the solution.

Исключения

Параметр documentPath или assemblyName имеет значение null или пуст.documentPath or assemblyName is null or empty.

documentPath или assemblyName ссылается на несуществующий файл.documentPath or assemblyName refers to a file that does not exist.

Документ, заданный параметром documentPath, уже содержит настройку.The document specified by documentPath already has a customization.

Документ, заданный параметром documentPath, поврежден или имеет ограниченные разрешения.The document specified by documentPath is corrupt, or has restricted permissions.

Документ, заданный параметром documentPath, имеет расширение имени файла, которое не поддерживается Набор средств Visual Studio для Office (cреда выполнения)Visual Studio Tools for Office runtime.The document specified by documentPath has a file name extension that is not supported by the Набор средств Visual Studio для Office (cреда выполнения)Visual Studio Tools for Office runtime.

Примеры

В следующем примере кода метод используется AddCustomization для присоединения настройки к указанному документу.The following code example uses the AddCustomization method to attach a customization to the specified document.

Для этого примера требуются:This example requires:

  • Проект консольного приложения или другой проект, не относящийся к Office.A console application project or some other non-Office project.

  • Ссылки на следующие сборки:References to the following assemblies:

    • Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll и Microsoft.VisualStudio.Tools.Applications.Runtime.dll (если проект предназначен для платформы .NET Framework 4.NET Framework 4 или .NET Framework 4.5.NET Framework 4.5).Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll and Microsoft.VisualStudio.Tools.Applications.Runtime.dll (if the project targets the .NET Framework 4.NET Framework 4 or the .NET Framework 4.5.NET Framework 4.5).

      oror

    • Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll и Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll (если проект предназначен для .NET Framework 3,5).Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll and Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll (if the project targets the .NET Framework 3.5).

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

Комментарии

AddCustomizationМетод связывает указанную настройку с документом, добавляя к _AssemblyName _AssemblyLocation документу и пользовательские свойства документа.The AddCustomization method associates the specified customization with the document by adding the _AssemblyName and _AssemblyLocation custom document properties to the document. Эти свойства определяют, что документ имеет настройку, и указывает расположение манифеста развертывания.These properties identify that the document has a customization and specify the location of the deployment manifest. После того как этот метод был успешно вызван, при следующем открытии указанного документа среда выполнения пытается установить решение Office.After this method is successfully called, the next time a user opens the specified document, the runtime attempts to install the Office solution. Дополнительные сведения о настраиваемых свойствах документа см. в разделе Общие сведения о пользовательских свойствахдокумента.For more information about the custom document properties, see Custom Document Properties Overview.

Идентификатор GUID, передаваемый в solutionID параметр, указывается в манифесте приложения решения, которое присоединяется к документу.The GUID that you pass to the solutionID parameter is specified in the application manifest of the solution that you are attaching to the document. Необходимо передать тот же идентификатор GUID, который указан в solutionId атрибуте vstov4:document элемента в манифесте приложения.You must pass the same GUID that is specified in the solutionId attribute of the vstov4:document element in the application manifest. Дополнительные сведения см. в разделе Манифесты приложения и развертывания в решениях Office и & lt; Document & gt; Элемент.For more information, see Application and Deployment Manifests in Office Solutions and <document> Element.

При присоединении настроек из расположения публикации убедитесь, что в параметре указано правильное имя файла для сборки assemblyName .If you are attaching a customization from a publish location, make sure that you specify the correct file name for the assembly in the assemblyName parameter. При публикации решения Office сборка, которая копируется в папку publish, имеет расширение. deploy.When you publish an Office solution, the assembly that is copied to the publish folder has the .deploy file name extension. Например, если имя сборки — WordDocument1.dll, имя файла сборки в папке Publish будет WordDocument1.dll. deploy.For example, if the assembly name is WordDocument1.dll, the file name of the assembly in the publish folder is WordDocument1.dll.deploy. Дополнительные сведения см. в статье развертывание решения Office с помощью ClickOnce.For more information, see Deploying an Office Solution by Using ClickOnce.

Если указанный документ не содержит элемент управления, который требуется для документа настройки, AddCustomization метод будет успешным, но сборка не будет загружена, когда пользователь откроет документ.If the specified document does not contain a control that the customization expects the document to have, the AddCustomization method will succeed, but the assembly will fail to load when the user opens the document.

fileTypeПараметр должен указывать документ с расширением имени файла, который поддерживается для настроек на уровне документа для Microsoft Office Word и Microsoft Office Excel.The fileType parameter must specify a document that has a file name extension that is supported for document-level customizations for Microsoft Office Word and Microsoft Office Excel. Невозможно присоединить настройку к документу, сохраненному в форматах XML-документов Word (* XML) или Word 2003 * .You cannot attach a customization to a document that is saved in the Word XML Document (*xml) or Word 2003 XML Document (*xml) file formats. Дополнительные сведения о поддерживаемых типах файлов см. в разделе Архитектура настроек на уровне документа.For more information about the supported file types, see Architecture of Document-Level Customizations.

Применяется к

AddCustomization(String, String, Guid, Uri, Boolean, String[])

public static void AddCustomization (string documentPath, string assemblyName, Guid solutionId, Uri deploymentManifestUrl, bool runAsLocal, out string[] nonpublicCachedDataMembers);

Параметры

documentPath
String
assemblyName
String
solutionId
Guid
deploymentManifestUrl
Uri
runAsLocal
Boolean
nonpublicCachedDataMembers
String[]

Применяется к