ServerDocument.AddCustomization - метод (String, String, Guid, Uri)

Статья
08/11/2011

Прикрепляет настройку к указанному документу с помощью заданного имени документа, сборки, ИД решения и манифеста развертывания.

Пространство имен: 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
GUID, по которому Среда выполнения Visual Studio Tools for Office идентифицирует решение.

deploymentManifestUrl
Тип: System.Uri
URL-адрес манифеста развертывания решения.

Исключения

Исключение	Условие
ArgumentNullException	Параметр documentPath или assemblyName имеет значение nullпустая ссылка (Nothing в Visual Basic) или пуст.
FileNotFoundException	Параметр documentPath или assemblyName ссылается на несуществующий файл.
DocumentAlreadyCustomizedException	В документе, указанном параметром documentPath, уже есть настройка.
DocumentNotCustomizedException	Документ, заданный параметром documentPath, поврежден или обладает ограниченными разрешениями.
UnknownCustomizationFileException	Среда Среда выполнения Visual Studio Tools for Office не поддерживает расширение имени файла документа, заданного параметром documentPath.

Заметки

Метод AddCustomization связывает указанную настройку с документом, добавляя к нему настраиваемые свойства _AssemblyName и _AssemblyLocation. Эти свойства указывают на то, что в документе есть настройка, и задают расположение манифеста развертывания. После успешного вызова этого метода при последующем открытии пользователем указанного документа среда выполнения пытается установить решение Office. Дополнительные сведения о настраиваемых свойствах документа см. в разделе Общие сведения о настраиваемых свойствах документа.

Переданный в параметр solutionID GUID указывается в манифесте приложения, таким образом происходит прикрепление документа. Необходимо передать тот же идентификатор GUID, который указан в атрибуте solutionId элемента vstov4:document в манифесте приложения. Дополнительные сведения см. в разделах Манифесты приложения и развертывания в решениях Office и Элемент <document> (разработка для Office в Visual Studio).

При прикреплении настройки из места публикации необходимо убедиться, что в параметре assemblyName задано верное имя файла сборки. При публикации решения Office сборка, которая копируется в каталог публикации, обладает расширением имени файла ".deploy". Так, если имя файла сборки — WordDocument.dll, то именем сборки в каталоге публикации будет WordDocument.dll.deploy. Дополнительные сведения см. в разделе Публикация решений Office.

Если указанный документ не содержит элемент управления, ожидаемый настройкой, вызов метода AddCustomization завершается успешно, однако при открытии документа пользователем загрузка сборки завершается с ошибкой.

Параметр fileType должен задавать документ, имеющий расширение имени файла, которое поддерживается в настройках уровня документа для Microsoft Office Word и Microsoft Office Excel. Нельзя прикрепить настройку к документу, сохраненного в форматах файлов XML-документа Word (*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);
    }
}

Безопасность платформы .NET Framework

Полное доверие для непосредственно вызывающего метода. Этот член не может быть использован частично доверенным кодом. Дополнительные сведения см. в разделе Использование библиотек из не вполне надежного кода.