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

Les arguments nommés et les arguments facultatifs, rendent la programmation en C# plus pratique, plus souple et plus lisible. De plus, ces fonctionnalités facilitent considérablement l’accès aux interfaces COM, telles que les API Microsoft Office Automation.

Important

VSTO (Visual Studio Tools pour Office) s’appuie sur .NET Framework. Les compléments COM peuvent également être écrits avec .NET Framework. Les compléments Office ne peuvent pas être créés avec .NET Core et .NET 5+, les dernières versions de .NET. En effet, .NET Core et .NET 5+ ne peuvent pas fonctionner avec .NET Framework dans le même processus, et cela peut entraîner des échecs de chargement des compléments. Vous pouvez continuer d’utiliser .NET Framework pour écrire des compléments VSTO et COM pour Office. Microsoft ne mettra pas à jour VSTO ou la plateforme de compléments COM pour utiliser .NET Core ou .NET 5+. Vous pouvez utiliser .NET Core et .NET 5+, dont 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 les caractéristiques d’une table, comme le nombre de colonnes et de lignes, la mise en forme, les bordures, les polices et les couleurs. Ces 16 paramètres sont facultatifs, car la plupart du temps, il n’est pas nécessaire de spécifier des valeurs pour chacun d’eux. Mais sans arguments nommés et facultatifs, vous devez fournir une valeur ou une valeur d’espace réservé. Avec les arguments nommés et facultatifs, vous spécifiez des valeurs uniquement pour les paramètres nécessaires à votre projet.

Pour que vous puissiez effectuer ces procédures, Microsoft Office Word doit être installé sur votre ordinateur.

Notes

Il est possible que pour certains des éléments de l'interface utilisateur de Visual Studio, votre ordinateur affiche des noms ou des emplacements différents de ceux indiqués dans les instructions suivantes. L'édition de Visual Studio dont vous disposez et les paramètres que vous utilisez déterminent ces éléments. Pour plus d’informations, consultez Personnalisation de 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 vérifier que .NET Framework 4, ou version ultérieure, apparaît dans la zone Framework cible. Dans le volet Modèles, sélectionnez Application console. Attribuez un nom à votre projet dans le champ Nom. Sélectionnez 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. Sélectionnez OK.

Ajouter les directives using 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 using suivantes en début du fichier de code :

using Word = Microsoft.Office.Interop.Word;

Afficher du texte dans un document Word

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

static void DisplayInWord()
{
    var wordApp = new Word.Application();
    wordApp.Visible = true;
    // 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();
}

Ajoutez le code suivant à la fin de la méthode pour définir l’emplacement d’affichage du texte dans le document, ainsi que le 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écution de l'application

Ajoutez l’instruction suivante à Main :

DisplayInWord();

Appuyez sur Ctrl+F5 pour exécuter le projet. Un document Word contenant le texte spécifié s’affiche.

Convertir le texte en tableau

Utilisez la méthode ConvertToTable pour inclure le texte dans un tableau. La méthode comporte 16 paramètres optionnels. IntelliSense place les paramètres facultatifs entre crochets, comme illustré dans l’exemple suivant.

Les arguments nommés et facultatifs permettent de spécifier des valeurs uniquement pour les paramètres que vous voulez modifier. Ajoutez le code suivant à la fin de la méthode DisplayInWord pour créer un tableau. L’argument spécifie que les virgules présentes dans le texte de la chaîne comprise dans range séparent les 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.

Tester d’autres paramètres

Modifiez le tableau de sorte qu’il comporte une colonne et trois lignes, remplacez la dernière ligne dans DisplayInWord par l’instruction suivante, puis appuyez sur CTRL+F5.

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

Spécifiez un format prédéfini pour le tableau, remplacez la dernière ligne dans DisplayInWord par l’instruction suivante, puis appuyez sur CTRL+F5. Le format peut être n’importe quelle constante WdTableFormat.

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

Exemple

Le code suivant contient 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();
            wordApp.Visible = true;
            // 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);
        }
    }
}