Didacticiel : partage de codes entre un complément VSTO et un complément Office avec une bibliothèque de codes partagée
Les compléments de Visual Studio Tools pour Office (VSTO) sont idéaux pour étendre Office afin de fournir des solutions aux entreprises, la vôtre ou d’autres. Ils existent depuis longtemps et des milliers de solutions sont créées avec VSTO. Cependant, ils s’exécutent uniquement avec Office sur Windows. Vous ne pouvez pas exécuter de compléments VSTO sur Mac, sur le web ou sur des plateformes mobiles.
Importante
Les compléments COM et VSTO ne sont pas pris en charge dans le nouvel Outlook sur Windows actuellement en préversion. Ces compléments sont toujours pris en charge dans le client de bureau Outlook sur Windows classique. Pour en savoir plus, voir Développer des compléments Outlook pour les nouveaux outlook sur Windows (préversion).
Les compléments Office utilisent HTML, JavaScript et d’autres technologies web pour créer des solutions Office sur toutes les plateformes. La migration de votre complément VSTO existant vers un complément Office est un excellent moyen de rendre votre solution accessible sur toutes les plateformes.
Vous pouvez conserver votre complément VSTO et un nouveau complément Office ayant les mêmes fonctionnalités. Cela vous permet de continuer à offrir un service à vos clients qui utilisent le complément VSTO pour Office sur Windows. Cela vous permet également de proposer aux clients la même fonctionnalité dans un complément Office pour l'ensemble des plateformes. Vous pouvez également Rendre votre complément Office compatible avec le complément VSTO existant.
Toutefois, il est préférable d’éviter de réécrire tout le code de votre complément VSTO pour le complément Office. Ce didacticiel explique les précautions à prendre pour éviter la réécriture d'un code grâce à l'utilisation d’une bibliothèque de codes partagés pour les deux compléments.
Bibliothèque de codes partagés
Ce tutoriel vous guide tout au long des étapes d’identification et de partage de code commun entre votre complément VSTO et un complément Office moderne. Il utilise un exemple de complément VSTO très simple pour les étapes afin que vous puissiez vous concentrer sur les compétences et techniques dont vous aurez besoin pour travailler avec vos propres compléments VSTO.
Le diagramme suivant illustre le fonctionnement de la bibliothèque de codes partagés pour la migration. Le code commun est refactorisé dans une nouvelle bibliothèque de codes partagés. Le code peut demeurer écrit dans son langage d’origine, par exemple C# ou VB. Cela signifie que vous continuez à utiliser le code dans le complément VSTO existant en créant une référence de projet. Lorsque vous créez le complément Office, celui-ci utilise également la bibliothèque de codes partagés en y appelant les API REST.
Compétences et techniques décrites dans ce didacticiel :
- Créer une bibliothèque de classes partagées en refactorisant le code dans une bibliothèque de classes .NET.
- Créez un wrapper API REST à l’aide de ASP.NET Core pour la bibliothèque de classes partagées.
- Appelez l’API REST à partir du complément Office pour accéder au code partagé.
Conditions préalables
Pour la configuration de votre environnement de développement :
- Installez Visual Studio 2019.
- Installez les charges de travail suivantes.
- ASP.NET et le développement web
- Développement multiplateforme .NET Core
- Développement Office/SharePoint
- Les éléments Individuels suivants.
- Visual Studio Tools pour Office (VSTO)
- Runtime .NET Core 3.0
Vous devez également disposer des éléments ci-après :
- Un compte Microsoft 365. Vous pouvez bénéficier d’un abonnement Microsoft 365 E5 développeur, qui inclut des applications Office, par le biais du Programme pour les développeurs Microsoft 365. Pour plus d’informations, consultez le FAQ. Vous pouvez également vous inscrire à un essai gratuit de 1 mois ou acheter un plan Microsoft 365.
- Un locataire Microsoft Azure. Un abonnement d’évaluation peut être obtenu ici : Microsoft Azure.
Le composant VSTO d’analyseur de cellule
Ce didacticiel utilise la solution PnP pour la Bibliothèque de compléments VSTO partagés pour les compléments Office. Le dossier /start contient la solution de complément VSTO que vous allez migrer. Votre objectif est de migrer le complément VSTO vers un complément Office moderne en partageant le code lorsque cela est possible.
Remarque
L’exemple utilise C#, mais vous pouvez appliquer les techniques de ce didacticiel à un complément VSTO écrit dans n’importe quel langage .NET.
- Téléchargez la solution PnP pour la Bibliothèque de compléments VSTO partagés pour les compléments Office vers un dossier de travail de votre ordinateur.
- Démarrez Visual Studio 2019 et ouvrez la solution /start/Cell-Analyzer.sln.
- Dans le menu Déboguer, choisissez Démarrer le débogage.
Le complément est un volet de tâche personnalisé Office pour Excel. Vous pouvez sélectionner n’importe quelle cellule contenant un texte, puis choisissez le bouton Afficher les Unicodes. Dans la section Résultat , le complément affiche une liste de chaque caractère du texte, ainsi que leur nombre Unicode correspondant.
Analyser les types de code dans le complément VSTO
La première technique à appliquer consiste à analyser le complément pour identifier les parties de code pouvant être partagées. Un projet se décompose généralement en trois types de codes.
Code d'interface utilisateur
Le code d'interface utilisateur communique avec l’utilisateur. Dans VSTO, le code d'interface utilisation fonctionne par le biais de Windows Forms. Les compléments Office utilisent les langages HTML, CSS et JavaScript pour l'interface utilisateur. En raison de ces différences, vous ne pouvez pas partager le code de l’interface utilisateur avec le complément Office. L’interface utilisateur doit être recréé dans JavaScript.
Code de document
Dans VSTO, le code interagit avec le document via des objets .NET, tels que Microsoft.Office.Interop.Excel.Range. Toutefois, les compléments Office utilisent la bibliothèque Office.js. Bien que ceux-ci soient similaires, ils ne sont pas exactement les mêmes. Là encore, vous ne pouvez pas partager le code d’interaction de document avec le complément Office.
Code logique
La logique métier, les algorithmes, les fonctions d’assistance et autres codes similaires constituent souvent le cœur d’un complément VSTO. Ce code fonctionne indépendamment de l’interface utilisateur et du code de document pour effectuer une analyse, se connecter à un service principale, effectuer des calculs, etc. Il s’agit du code qui peut être partagé pour que vous n’ayez pas à le réécrire dans JavaScript.
Examinez le complément VSTO. Dans le code suivant, chaque section est identifiée en tant que code de DOCUMENT, d’interface utilisateur ou d’ALGORITHME.
// *** UI CODE ***
private void btnUnicode_Click(object sender, EventArgs e)
{
// *** DOCUMENT CODE ***
Microsoft.Office.Interop.Excel.Range rangeCell;
rangeCell = Globals.ThisAddIn.Application.ActiveCell;
string cellValue = "";
if (null != rangeCell.Value)
{
cellValue = rangeCell.Value.ToString();
}
// *** ALGORITHM CODE ***
//convert string to Unicode listing
string result = "";
foreach (char c in cellValue)
{
int unicode = c;
result += $"{c}: {unicode}\r\n";
}
// *** UI CODE ***
//Output the result
txtResult.Text = result;
}
À l’aide de cette approche, vous pouvez voir qu’une section de code peut être partagée avec le complément Office. Le code suivant doit être refactorisé dans une bibliothèque de classes distincte.
// *** ALGORITHM CODE ***
//convert string to Unicode listing
string result = "";
foreach (char c in cellValue)
{
int unicode = c;
result += $"{c}: {unicode}\r\n";
}
Créer une bibliothèque de classes partagées
Les compléments VSTO étant créés dans Visual Studio en tant que projets .NET, nous réutiliser .NET aussi souvent que possible pour simplifier les choses. La technique suivante consiste à créer une bibliothèque de classes et à refactoriser le code partagé dans cette bibliothèque.
Si ce n'est pas encore fait, démarrez Visual Studio 2019 et ouvrez la solution /start/Cell-Analyzer.sln.
Cliquez avec le bouton droit sur la solution dans Explorateur de solutions et choisissez Ajouter un > nouveau projet.
Dans la boîte de dialogue Ajouter un nouveau projet, choisissez Bibliothèque de classes (.NET Framework), puis sélectionnez Suivant.
Remarque
N’utilisez pas la bibliothèque de classes .NET Core, car elle ne fonctionnera pas avec votre projet VSTO.
Dans la boîte de dialogue Configurer votre nouveau projet, définissez les champs suivants.
- Donnez un Nom de projet à CellAnalyzerSharedLibrary.
- Conservez la valeur par défaut location .
- Configurez Framework sur 4.7.2.
Sélectionnez Créer.
Une fois le projet créé, renommez le fichier Class1.cs dans CellOperations.cs. Une invite apparaît pour renommer la classe. Renommez le nom de classe pour qu’il corresponde au nom du fichier.
Ajoutez le code suivant à la classe
CellOperationspour créer une méthode nomméeGetUnicodeFromText.public class CellOperations { static public string GetUnicodeFromText(string value) { string result = ""; foreach (char c in value) { int unicode = c; result += $"{c}: {unicode}\r\n"; } return result; } }
Utiliser la bibliothèque de classes partagées dans le complément VSTO
Vous devez maintenant mettre à jour le complément VSTO pour utiliser la bibliothèque de classes. Il est important que les compléments VSTO et Office utilisent la même bibliothèque de classes partagées pour permettre de réaliser au même endroit les résolutions de bogues et les fonctionnalités.
Dans Explorateur de solutions, cliquez avec le bouton droit sur le projet Analyseur de cellule, puis choisissez Ajouter une référence.
Sélectionnez CellAnalyzerSharedLibrary, puis choisissez OK.
Dans Explorateur de solutions, développez le projet Analyseur de cellule, cliquez avec le bouton droit sur le fichier CellAnalyzerPane.cs, puis choisissez Afficher le code.
Dans la méthode
btnUnicode_Click, supprimez les lignes de code suivantes.//Convert to Unicode listing string result = ""; foreach (char c in cellValue) { int unicode = c; result += $"{c}: {unicode}\r\n"; }Mettez à jour la ligne de code sous le commentaire à lire
//Output the resultcomme suit ://Output the result txtResult.Text = CellAnalyzerSharedLibrary.CellOperations.GetUnicodeFromText(cellValue);Dans le menu Déboguer, choisissez Démarrer le débogage. Le volet Office personnalisé doit fonctionner comme attendu. Entrez du texte dans une cellule, puis vérifiez que vous pouvez le convertir en liste Unicode avec le complément.
Créer un wrapper API REST
Le complément VSTO peut utiliser directement la bibliothèque de classes partagée car tous deux sont des projets .NET. Le complément Office ne pourra toutefois pas utiliser .NET car il utilise JavaScript. Ensuite, vous allez créer un wrapper d’API REST. Le complément Office peut ainsi appeler une API REST, qui transmet ensuite l’appel vers la bibliothèque de classes partagée.
Dans Explorateur de solutions, cliquez avec le bouton droit sur le projet Analyseur de cellule, puis choisissez Ajouter un > nouveau projet.
Dans laboîte de dialogue Ajouter un nouveau projet, choisissez Application web ASP.NET Core, puis sélectionnez Suivant.
Dans la boîte de dialogue Configurer votre nouveau projet, définissez les champs suivants.
- Donnez un Nom de projet à CellAnalyzerRESTAPI.
- Dans le champ Emplacement, conserver la valeur par défaut.
Sélectionnez Créer.
Dans la boîte de dialogue Créer une application web ASP.NET Core, sélectionnez ASP.NET Core 3.1 pour la version, puis sélectionnez l'API dans la liste ds projets.
Conservez les valeurs par défaut dans tous les autres champs, puis sélectionnez le bouton Créer.
Une fois le projet créé, développez le projet CellAnalyzerRESTAPI dans l'Explorateur de solutions.
Cliquez avec le bouton droit sur Dépendances, puis sélectionnez Ajouter une référence.
Sélectionnez CellAnalyzerSharedLibrary, puis choisissez OK.
Cliquez avec le bouton droit sur le dossier Contrôleurs , puis choisissez Ajouter un > contrôleur.
Dans la boîte de dialogue Ajouter un nouvel élément généré automatiquement, choisissez Contrôleur d’API - Vide, puis Ajouter.
Dans la boîte de dialogue Ajouter un contrôleur d’API vide , nommez le contrôleur AnalyzeUnicodeController, puis choisissez Ajouter.
Ouvrez le fichier AnalyzeUnicodeController.cs et ajoutez le code suivant en tant que méthode à la classe
AnalyzeUnicodeController.[HttpGet] public ActionResult<string> AnalyzeUnicode(string value) { if (value == null) { return BadRequest(); } return CellAnalyzerSharedLibrary.CellOperations.GetUnicodeFromText(value); }Cliquez avec le bouton droit sur le projet CellAnalyzerRESTAPI, puis choisissez Définir comme projet de démarrage.
Dans le menu Déboguer, choisissez Démarrer le débogage.
Un navigateur s’ouvre. Entrez l’URL suivante pour vérifier que l’API REST fonctionne :
https://localhost:<ssl port number>/api/analyzeunicode?value=test. Vous pouvez réutiliser le numéro de port à partir de l’URL dans le navigateur lancé par Visual Studio. Vous devriez voir une chaîne renvoyée avec des valeurs Unicode pour chaque caractère.
Créer le complément Office
Lorsque vous créez le complément Office, celui-ci appelle l'API REST. Mais vous devez tout d'abord obtenir le numéro de port du serveur API REST et de l’enregistrer pour plus tard.
Enregistrer le numéro de port SSL
- Si ce n'est pas encore fait, démarrez Visual Studio 2019 et ouvrez la solution \start\Cell-Analyzer.sln.
- Dans le projet CellAnalyzerRESTAPI, développez les Propriétéset ouvrez le fichier launchSettings.json.
- Recherchez la ligne de code contenant la valeur de sslPort, copiez le numéro de port et enregistrez-le quelque part.
Ajouter le projet de complément Office
Pour simplifier les choses, conservez tous les codes dans une seule solution. Ajoutez le projet de complément Office à la solution Visual Studio existante. Toutefois, si vous êtes familiarisé avec le générateur Yeoman pour les compléments Office et Visual Studio Code, vous pouvez également exécuter yo office pour générer le projet. Les étapes sont très semblables.
- Dans Explorateur de solutions, cliquez avec le bouton droit sur la solution Cell-Analyzer, puis choisissez Ajouter un > nouveau projet.
- Dans la Boîte de dialogue Ajouter un nouveau projet, choisissez Complément web Excel, puis sélectionnez Suivant.
- Dans la boîte de dialogue Configurer votre nouveau projet, définissez les champs suivants.
- Donnez un Nom de projet à CellAnalyzerOfficeAddin.
- Conservez la valeur par défaut location .
- Configurez Framework sur 4.7.2 ou une version ultérieure.
- Sélectionnez Créer.
- Dans la boîte de dialogue Choisir le type de complément, sélectionnez Ajouter e nouvelles fonctionnalités dans Excel, puis choisissez Terminer.
Deux projets sont créés :
- CellAnalyzerOfficeAddin : ce projet configure les fichiers XML du manifeste qui décrivent le complément pour qu’Office puisse le charger correctement. Il contient l’ID, le nom, la description et d’autres informations sur le complément.
- CellAnalyzerOfficeAddinWeb : ce projet contient des ressources Web pour votre complément (par exemple, HTML, CSS et des scripts). Il configure également une instance IIS Express pour héberger votre complément en tant qu’application Web.
Ajouter des interfaces utilisateur et des fonctionnalités au complément Office
Dans l'Explorateur de solutions, développez le projet CellAnalyzerOfficeAddinWeb.
Ouvrez le fichier Home.html et remplacez le contenu
<body>par l'HTML suivant.<button id="btnShowUnicode" onclick="showUnicode()">Show Unicode</button> <p>Result:</p> <div id="txtResult"></div>Ouvrez ce fichier Home.js et remplacez l’intégralité de son contenu par le code suivant.
(function () { "use strict"; // The initialize function must be run each time a new page is loaded. Office.initialize = function (reason) { $(document).ready(function () { }); }; })(); function showUnicode() { Excel.run(function (context) { const range = context.workbook.getSelectedRange(); range.load("values"); return context.sync(range).then(function (range) { const url = "https://localhost:<ssl port number>/api/analyzeunicode?value=" + range.values[0][0]; $.ajax({ type: "GET", url: url, success: function (data) { let htmlData = data.replace(/\r\n/g, '<br>'); $("#txtResult").html(htmlData); }, error: function (data) { $("#txtResult").html("error occurred in ajax call."); } }); }); }); }Dans le code précédent, entrez le numéro de sslPort que vous avez enregistré précédemment à partir du fichier launchSettings.json.
Dans le code précédent, la chaîne retournée est traitée pour remplacer les flux de ligne de retour chariot par des <br> balises HTML. Vous pouvez parfois être confronté(e) à des situations dans lesquelles une valeur de retour fonctionnant parfaitement pour .NET dans le complément VSTO doit être ajustée sur le côté du complément Office pour fonctionner comme attendu. Dans ce cas, l’API REST et la bibliothèque de classes partagées sont uniquement concernées par le retour de la chaîne. La fonction showUnicode() est chargée de la mise en forme correcte des valeurs de retour pour la présentation.
Autoriser CORS à partir d'un complément Office
La bibliothèque Office.js nécessite CORS pour les appels sortants, tels que ceux effectués à partir de l’appel ajax vers le serveur API REST. Pour autoriser des appels du complément Office vers l’API REST, procédez comme suit.
Dans l'Explorateur de solutions, sélectionnez le projet CellAnalyzerOfficeAddinWeb.
Dans le menu Affichage , choisissez Fenêtre Propriétés, si la fenêtre n’est pas déjà affichée.
Dans la fenêtre des propriétés, copiez et enregistrez la valeur de l'URL SSL. Il s’agit de l’URL que vous devez autoriser dans CORS.
Dans le projet CellAnalyzerRESTAPI, ouvrez le fichier Startup.cs.
Ajoutez le code suivant en haut de la méthode
ConfigureServices. Assurez-vous de remplacer l’URL SSL que vous avez copiée précédemment pour l’appelbuilder.WithOrigins.services.AddCors(options => { options.AddPolicy(MyAllowSpecificOrigins, builder => { builder.WithOrigins("<your URL SSL>") .AllowAnyMethod() .AllowAnyHeader(); }); });Remarque
Enlevez le
/qui se trouve à la fin de l’URL lorsque vous l’utilisez dans la méthodebuilder.WithOriginsBuilder.WithOrigins.tr. Par exemple, il doit ressembler àhttps://localhost:44000. Sinon, vous obtiendrez une erreur CORS lors de l’exécution.Ajoutez le champ suivant à la classe
Startup.readonly string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";Ajoutez le code suivant à la méthode
configurejuste avant la ligne de code pourapp.UseEndpoints.app.UseCors(MyAllowSpecificOrigins);
Lorsque vous avez terminé, votre classe Startup doit ressembler au code suivant (votre URL localhost peut être différente).
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
readonly string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";
public IConfiguration Configuration { get; }
// NOTE: The following code configures CORS for the localhost:44397 port.
// This is for development purposes. In production code, you should update this to
// use the appropriate allowed domains.
public void ConfigureServices(IServiceCollection services)
{
services.AddCors(options =>
{
options.AddPolicy(MyAllowSpecificOrigins,
builder =>
{
builder.WithOrigins("https://localhost:44397")
.AllowAnyMethod()
.AllowAnyHeader();
});
});
services.AddControllers();
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseHttpsRedirection();
app.UseRouting();
app.UseAuthorization();
app.UseCors(MyAllowSpecificOrigins);
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}
}
Exécuter du complément
Dans l’Explorateur de solutions, cliquez à l'aide du nœud supérieur sur la Solution de l'analyseur de cellules, puis choisissez Configurer les projets de départ.
Dans la boîte de dialogue des Pages de propriété de la solution de l'analyseur de cellules, sélectionnez Plusieurs projets de départ.
Définissez la propriété action au Départ pour chacun des projets suivants.
- CellAnalyzerRESTAPI
- CellAnalyzerOfficeAddin
- CellAnalyzerOfficeAddinWeb
Sélectionnez OK.
Dans le menu Déboguer, choisissez Démarrer le débogage.
Excel exécute et charge une version test du complément Office. Vous pouvez vérifier que le service API REST localhost fonctionne correctement en entrant une valeur de texte dans une cellule, puis en sélectionnant le bouton Afficher l'Unicode dans le complément Office. Il doit appeler l’API REST et afficher les valeurs Unicode pour les caractères de texte.
Publier vers Azure App Service
Vous voulez enfin publier le projet API REST sur le cloud. Dans les étapes suivantes, vous allez découvrir comment publier le projet CellAnalyzerRESTAPI dans Microsoft Azure App Service. Pour plus d’informations sur l’obtention d’un compte Azure, voir les Conditions préalables.
- Dans l’Explorateur de solutions, cliquez à l'aide du bouton droit sur le projet CellAnalyzerRESTAPI, puis choisissez Publier.
- Dans la boîte de dialogue Sélectionner une cible de publication, sélectionnez Créer nouveau, puis choisissez Créer un profil.
- Dans la boîte de dialogue App Service, sélectionnez le compte approprié, s’il n’est pas déjà sélectionné.
- Les valeurs par défaut sont utilisées dans les champs de la boîte de dialogue App Service de votre compte. En règle générale, les valeurs par défaut fonctionnent correctement, mais vous pouvez les modifier si vous préférez des paramètres différents.
- Dans la boîte de dialogue App Service, sélectionnez Créer.
- Le nouveau profil s’affiche dans une page Publier. Sélectionnez Publier pour créer et déployer le code vers App Service.
Vous pouvez maintenant tester le service. Ouvrez un navigateur et entrez une URL qui accède directement au nouveau service. Par exemple, utilisez https://<myappservice>.azurewebsites.net/api/analyzeunicode?value=test, où myappservice est le nom unique que vous avez créé pour la nouvelle App Service.
Utiliser Azure App Service à partir du complément Office
La dernière étape consiste à mettre à jour le code dans le complément Office pour utiliser Azure App Service au lieu de localhost.
Dans l'Explorateur de solutions, développez le projet CellAnalyzerOfficeAddinWeb et ouvrez le fichier Home.js.
Modifiez la constante
urlafin d’utiliser l’URL d'Azure App Service, comme illustré dans la ligne de code suivante. Remplacez<myappservice>par le nom unique que vous avez créé pour le nouvel App Service.const url = "https://<myappservice>.azurewebsites.net/api/analyzeunicode?value=" + range.values[0][0];Dans l’Explorateur de solutions, cliquez à l'aide du nœud supérieur sur la Solution de l'analyseur de cellules, puis choisissez Configurer les projets de départ.
Dans la boîte de dialogue des Pages de propriété de la solution de l'analyseur de cellules, sélectionnez Plusieurs projets de départ.
Activez l’action Démarrer pour chacun des projets suivants.
- CellAnalyzerOfficeAddinWeb
- CellAnalyzerOfficeAddin
Sélectionnez OK.
Dans le menu Déboguer, choisissez Démarrer le débogage.
Excel exécute et charge une version test du complément Office. Pour vérifier que App Service fonctionne correctement, entrez une valeur de texte dans une cellule, puis choisissez Afficher l'Unicode dans le complément Office. Il doit appeler le service et afficher les valeurs Unicode pour les caractères de texte.
Conclusion
Dans ce tutoriel, vous avez appris à créer un complément Office qui utilise du code partagé avec le complément VSTO d’origine. Vous avez appris à gérer le code VSTO pour Office sur Windows et un complément Office pour Office sur d’autres plateformes. Vous avez refactorisé un code C# VSTO dans une bibliothèque partagée et vous l’avez déployé dans Azure App Service. Vous avez créé un complément Office qui utilise la bibliothèque partagée afin que vous n’ayez pas à réécrire le code en JavaScript.
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour