ServerDocument.AddCustomization, méthode (String, String, Guid, Uri)

Article
01/06/2014

Joint une personnalisation au document spécifié en utilisant le document, le nom d''assembly, l'ID de solution et le manifeste de déploiement spécifiés.

Espace de noms : Microsoft.VisualStudio.Tools.Applications
Assembly : Microsoft.VisualStudio.Tools.Applications.ServerDocument (dans Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll)

Syntaxe

'Déclaration
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
)

Paramètres

documentPath
Type : System.String
Chemin d'accès complet du document auquel vous voulez joindre une personnalisation.

assemblyName
Type : System.String
Chemin d'accès complet de l'assembly de la personnalisation.Le chemin d'accès doit se trouver dans le système de fichiers local ou un partage UNC ; vous ne pouvez pas spécifier un emplacement HTTP.

solutionId
Type : System.Guid
GUID que Visual Studio Tools pour Office Runtime utilise pour identifier la solution.

deploymentManifestUrl
Type : System.Uri
URL du manifeste de déploiement pour la solution.

Exceptions

Exception	Condition
ArgumentNullException	documentPath ou assemblyName est nullune référence null (Nothing en Visual Basic) ou vide.
FileNotFoundException	documentPath ou assemblyName fait référence à un fichier qui n'existe pas.
DocumentAlreadyCustomizedException	Le document spécifié par documentPath a déjà une personnalisation.
DocumentNotCustomizedException	Le document spécifié par documentPath est corrompu ou il a des autorisations limitées.
UnknownCustomizationFileException	Le document spécifié par documentPath a une extension de nom de fichier qui n'est pas prise en charge par Visual Studio Tools pour Office Runtime.

Notes

La méthode AddCustomization associe la personnalisation spécifiée au document en ajoutant les propriétés de document personnalisées _AssemblyName et _AssemblyLocation au document. Ces propriétés identifient que le document a une personnalisation et spécifient l'emplacement du manifeste de déploiement. Après l'appel de cette méthode, la prochaine fois qu'un utilisateur ouvre le document spécifié, l'exécution essaie d'installer la solution Office. Pour plus d'informations sur les propriétés de document personnalisées, consultez Vue d'ensemble des propriétés de document personnalisées.

Le GUID que vous passez au paramètre solutionID est spécifié dans le manifeste de l'application de la solution que vous joignez au document. Vous devez passer le même GUID spécifié dans l'attribut solutionId de l'élément vstov4:document dans le manifeste de l'application. Pour plus d’informations, consultez Manifestes d'application et de déploiement dans les solutions Office et <document>, élément (Développement Office dans Visual Studio).

Si vous joignez une personnalisation depuis un emplacement de publication, veillez à définir le nom de fichier correct de l'assembly dans le paramètre assemblyName. Lorsque vous publiez une solution Office, l'assembly copié dans le dossier de publication a l'extension de nom de fichier .deploy. Par exemple, si le nom de l'assembly est WordDocument1.dll, le nom de fichier de l'assembly dans le dossier de publication est WordDocument1.dll.deploy. Pour plus d'informations, consultez Déploiement d'une solution Office à l'aide de ClickOnce.

Si le document spécifié ne contient pas un contrôle que la personnalisation s'attend à trouver dans le document, la méthode AddCustomization aboutit, mais le chargement de l'assembly échoue lorsque l'utilisateur ouvre le document.

Le paramètre fileType doit spécifier un document qui a une extension de nom de fichier prise en charge pour les personnalisations au niveau du document pour Microsoft Office Word et Microsoft Office Excel. Vous ne pouvez pas joindre de personnalisation à un document enregistré au format de fichier Document XML Word (*.xml) ou Document Word 2003 XML (*.xml). Pour plus d'informations sur les types de fichiers pris en charge, consultez Architecture des personnalisations au niveau du document.

Exemples

L'exemple de code suivant utilise la méthode AddCustomization pour joindre une personnalisation au document spécifié.

Cet exemple nécessite :

Projet d'application console ou un autre projet non-Office.
Références aux assemblys suivants :
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll et Microsoft.VisualStudio.Tools.Applications.Runtime.dll (si le projet cible .NET Framework 4 ou .NET Framework 4.5).
  
  ou
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll et Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll (si le projet cible le .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);
    }
}

Sécurité .NET Framework

Confiance totale accordée à l'appelant immédiat. Ce membre ne peut pas être utilisé par du code d'un niveau de confiance partiel. Pour plus d'informations, consultez Utilisation de bibliothèques à partir de code d'un niveau de confiance partiel.