Comment utiliser des arguments nommés et facultatifs dans la programmation Office

Les arguments nommés et les arguments facultatifs améliorent la commodité, la flexibilité et la lisibilité dans la programmation C#. En outre, ces fonctionnalités facilitent considérablement l’accès aux interfaces COM telles que les API Microsoft Office Automation.

Importante

VSTO (Visual Studio Tools pour Office) s’appuie sur .NET Framework. Les compléments COM peuvent également être écrits avec le .NET Framework. Les compléments Office ne peuvent pas être créés avec .NET Core et .NET 5+, les dernières versions de .NET. Cela est dû au fait que .NET Core/.NET 5+ ne peut pas fonctionner avec .NET Framework dans le même processus, ce qui peut entraîner des échecs de chargement d'add-ins. Vous pouvez continuer à utiliser .NET Framework pour écrire des compléments VSTO et COM pour Office. Microsoft ne met pas à jour VSTO ou la plateforme de complément COM pour utiliser .NET Core ou .NET 5+. Vous pouvez tirer parti de .NET Core et .NET 5+, notamment ASP.NET Core, pour créer le côté serveur des compléments Web Office.

Dans l’exemple suivant, la méthode ConvertToTable a 16 paramètres qui représentent des caractéristiques d’une table, telles que le nombre de colonnes et de lignes, la mise en forme, les bordures, les polices et les couleurs. Tous les 16 paramètres sont facultatifs, car la plupart du temps, vous ne souhaitez pas spécifier de valeurs particulières pour tous ces paramètres. Toutefois, sans arguments nommés et facultatifs, vous devez fournir une valeur ou une valeur par défaut. Avec des arguments nommés et facultatifs, vous spécifiez des valeurs uniquement pour les paramètres requis pour votre projet.

Microsoft Office Word doit être installé sur votre ordinateur pour effectuer ces procédures.

Remarque

Votre ordinateur peut afficher différents noms ou emplacements pour certains des éléments de l’interface utilisateur Visual Studio dans les instructions suivantes. L’édition Visual Studio que vous avez et les paramètres que vous utilisez déterminent ces éléments. Pour plus d’informations, consultez Personnaliser l’IDE.

Créer une application console

Démarrez Visual Studio. Dans le menu Fichier , pointez sur Nouveau, puis sélectionnez Projet. Dans le volet Catégories de modèles , développez C#, puis sélectionnez Windows. Regardez en haut du volet Modèles pour vous assurer que .NET Framework 4 apparaît dans la zone Framework cible . Dans le volet Modèles , sélectionnez Application console. Tapez un nom pour votre projet dans le champ Nom . Cliquez sur OK. Le nouveau projet s’affiche dans l’Explorateur de solutions.

Ajouter une référence

Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le nom de votre projet, puis sélectionnez Ajouter une référence. La boîte de dialogue Ajouter une référence s’affiche. Dans la page .NET , sélectionnez Microsoft.Office.Interop.Word dans la liste Nom du composant . Cliquez sur OK.

Ajouter les directives d’utilisation nécessaires

Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le fichier Program.cs , puis sélectionnez Afficher le code. Ajoutez les directives suivantes using en haut du fichier de code :

using Word = Microsoft.Office.Interop.Word;

Afficher du texte dans un document Word

Dans la Program classe de Program.cs, ajoutez la méthode suivante pour créer une application Word et un document Word. La méthode Add a quatre paramètres facultatifs. Cet exemple utilise leurs valeurs par défaut. Par conséquent, aucun argument n’est nécessaire dans la déclaration d'appel.

Remarque

Pour éviter les problèmes de thread et de minutage COM qui peuvent entraîner des exceptions telles que « Le filtre de messages a indiqué que l’application est occupée » (HRESULT 0x8001010A), l’application Word est conservée invisible pendant les opérations et n’est rendue visible qu’une fois toutes les opérations terminées.

static void DisplayInWord()
{
    var wordApp = new Word.Application();
    // Keep Word invisible during operations to avoid COM threading issues
    wordApp.Visible = false;
    // docs is a collection of all the Document objects currently
    // open in Word.
    Word.Documents docs = wordApp.Documents;

    // Add a document to the collection and name it doc.
    Word.Document doc = docs.Add();
    
    // Make Word visible after operations are complete
    wordApp.Visible = true;
}

Ajoutez le code suivant à la fin de la méthode pour définir où afficher du texte dans le document et quel texte afficher :

// Define a range, a contiguous area in the document, by specifying
// a starting and ending character position. Currently, the document
// is empty.
Word.Range range = doc.Range(0, 0);

// Use the InsertAfter method to insert a string at the end of the
// current range.
range.InsertAfter("Testing, testing, testing. . .");

Exécuter l’application

Ajoutez l’instruction suivante à Main :

DisplayInWord();

Appuyez sur Ctrl+F5 pour exécuter le projet. Un document Word apparaît qui contient le texte spécifié.

Modifier le texte d’un tableau

Utilisez la ConvertToTable méthode pour placer le texte dans un tableau. La méthode a 16 paramètres facultatifs. IntelliSense place les paramètres facultatifs entre crochets, comme illustré dans l’illustration suivante. Les valeurs Type.Missing par défaut sont le nom simple pour System.Type.Missing.

Les arguments nommés et facultatifs vous permettent de spécifier des valeurs uniquement pour les paramètres que vous souhaitez modifier. Ajoutez le code suivant à la fin de la méthode DisplayInWord pour créer une table. L’argument spécifie que les virgules de la chaîne range de texte se séparent des cellules du tableau.

// Convert to a simple table. The table will have a single row with
// three columns.
range.ConvertToTable(Separator: ",");

Appuyez sur Ctrl+F5 pour exécuter le projet.

Expérimenter avec d’autres paramètres

Modifiez la table pour qu’elle comporte une colonne et trois lignes, remplacez la dernière ligne DisplayInWord par l’instruction suivante, puis tapez Ctrl+F5.

range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1);

Spécifiez un format prédéfini pour le tableau, remplacez la dernière ligne DisplayInWord par l’instruction suivante, puis tapez Ctrl+F5. Le format peut être l’une des constantes WdTableFormat .

range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1,
    Format: Word.WdTableFormat.wdTableFormatElegant);

Exemple :

Le code suivant inclut l’exemple complet :

using System;
using Word = Microsoft.Office.Interop.Word;

namespace OfficeHowTo
{
    class WordProgram
    {
        static void Main(string[] args)
        {
            DisplayInWord();
        }

        static void DisplayInWord()
        {
            var wordApp = new Word.Application();
            // Keep Word invisible during operations to avoid COM threading issues
            wordApp.Visible = false;
            // docs is a collection of all the Document objects currently
            // open in Word.
            Word.Documents docs = wordApp.Documents;

            // Add a document to the collection and name it doc.
            Word.Document doc = docs.Add();

            // Define a range, a contiguous area in the document, by specifying
            // a starting and ending character position. Currently, the document
            // is empty.
            Word.Range range = doc.Range(0, 0);

            // Use the InsertAfter method to insert a string at the end of the
            // current range.
            range.InsertAfter("Testing, testing, testing. . .");

            // You can comment out any or all of the following statements to
            // see the effect of each one in the Word document.

            // Next, use the ConvertToTable method to put the text into a table.
            // The method has 16 optional parameters. You only have to specify
            // values for those you want to change.

            // Convert to a simple table. The table will have a single row with
            // three columns.
            range.ConvertToTable(Separator: ",");

            // Change to a single column with three rows..
            range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1);

            // Format the table.
            range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1,
                Format: Word.WdTableFormat.wdTableFormatElegant);

            // Make Word visible after all operations are complete
            wordApp.Visible = true;
        }
    }
}