Mettre à niveau un projet côté serveur WCF vers CoreWCF
Article
L’Assistant Mise à niveau .NET est un outil de ligne de commande qui aide à mettre à niveau un projet WCF côté serveur existant sur .NET Framework afin d’utiliser les services CoreWCF sur .NET 6. Cet article fournit :
Ce qu’il faut savoir avant de commencer.
Une démonstration de la façon d’exécuter l’outil sur un projet côté serveur WCF sur .NET Framework.
Conseils en matière de résolution des problèmes.
Ce qu’il faut savoir avant de commencer
Cet outil prend actuellement en charge les projets C# et utilise CoreWCF pour porter des projets WCF auto-hébergés côté serveur vers .NET 6.
Important
La mise à niveau des projets WCF nécessite une version héritée de l’Assistant Mise à niveau .NET et n’est pas compatible avec les dernières versions. Des instructions sur l’installation de la version héritée sont fournies dans la section Installer la version héritée.
Pour qu’un projet WCF soit applicable à cette mise à niveau, il doit répondre aux exigences suivantes :
Inclut un fichier .cs qui référence System.ServiceModel et crée un nouveau ServiceHost.
Si le projet WCF a plusieurs ServiceHost, tous les hôtes doivent être créés dans la même méthode.
Inclut un fichier .config qui stocke les propriétés System.ServiceModel.
La version actuelle de l’outil ne prend pas en charge les projets WCF hébergés via des fichiers .svc.
Si vous avez configuré des sources de flux NuGet supplémentaires, l’installation peut échouer avec une erreur indiquant que le package NuGet n’est pas disponible dans le flux. Utilisez le --ignore-failed-sources paramètre pour traiter ces échecs comme des avertissements au lieu d’erreurs, en contournant les autres sources de flux NuGet :
Vous pouvez utiliser l’exemple de projet Calculatrice de base pour tester la mise à niveau avec l’Assistant Mise à niveau, qui est également la démonstration utilisée dans cette documentation.
Si vous voulez essayer un exemple plus complexe, consultez l’exemple BeanTrader créé par Mike Rousos.
Exécuter l’Assistant Mise à niveau
Ouvrez un terminal et accédez au dossier où se trouve le projet ou la solution cible. Exécutez la commande upgrade-assistant upgrade en passant le nom du projet ou de la solution que vous mettez à niveau.
Quand un projet est spécifié, le processus de mise à niveau démarre immédiatement sur ce projet. Si une solution est fournie, vous sélectionnez le projet que vous exécutez normalement, appelé « point d’entrée de mise à niveau ». Basé sur ce projet, un graphique des dépendances est créé et une suggestion sur l’ordre dans lequel vous devez mettre à niveau les projets est fournie.
Console
upgrade-assistant upgrade .\CalculatorSample.sln
L’outil s’exécute et vous montre une liste des étapes qu’il va effectuer. À mesure que chaque étape est effectuée, l’outil fournit un ensemble de commandes permettant à l’utilisateur d’appliquer ou d’ignorer l’étape suivante ou une autre option, comme par exemple :
Obtenir plus d’informations sur l’étape.
Changer les projets.
Ajuster les paramètres de journalisation.
Arrêter la mise à niveau et quitter.
Si vous appuyez sur Entrée sans choisir un numéro, c’est le premier élément de la liste qui est sélectionné.
À mesure que chaque étape s’initialise, elle peut fournir des informations sur ce qui peut se produire si vous appliquez l’étape.
Sélectionner le point d’entrée et le projet à mettre à niveau
La première étape de la mise à niveau de l’exemple de calculatrice de base consiste à choisir le projet dans la solution qui sert de projet de point d’entrée.
Output
Upgrade Steps
1. [Next step] Select an entrypoint
2. Select project to upgrade
Choose a command:
1. Apply next step (Select an entrypoint)
2. Skip next step (Select an entrypoint)
3. See more step details
4. Configure logging
5. Exit
Choisissez la commande 1 pour démarrer cette étape. Les résultats sont affichés :
Output
[10:25:42 INF] Applying upgrade step Select an entrypoint
Please select the project you run. We will then analyze the dependencies and identify the recommended order to upgrade projects.
1. CalculatorClient
2. CalculatorService
Deux projets sont listés. Comme notre outil met à niveau le projet côté serveur, nous allons choisir la commande 2 pour sélectionner le projet de service comme point d’entrée.
Mettre à niveau le projet
Une fois qu’un projet est sélectionné, une liste des étapes de mise à niveau qui seront effectuées par l’outil est affichée.
Important
En fonction du projet que vous mettez à niveau, vous pouvez ou non voir toutes les étapes listées dans cet exemple.
La sortie suivante décrit les étapes impliquées dans la mise à niveau du projet :
Output
Upgrade Steps
Entrypoint: C:\Users\Desktop\CalculatorSample\CalculatorService\CalculatorService.csproj
Current Project: C:\Users\Desktop\CalculatorSample\CalculatorService\CalculatorService.csproj
1. [Next step] Back up project
2. Convert project file to SDK style
3. Clean up NuGet package references
a. Duplicate reference analyzer
b. Package map reference analyzer
c. Target compatibility reference analyzer
d. Upgrade assistant reference analyzer
e. Windows Compatibility Pack Analyzer
f. MyDotAnalyzer reference analyzer
g. Newtonsoft.Json reference analyzer
h. Windows App SDK package analysis
i. Transitive reference analyzer
4. Update TFM
5. Update NuGet Packages
a. Duplicate reference analyzer
b. Package map reference analyzer
c. Target compatibility reference analyzer
d. Upgrade assistant reference analyzer
e. Windows Compatibility Pack Analyzer
f. MyDotAnalyzer reference analyzer
g. Newtonsoft.Json reference analyzer
h. Windows App SDK package analysis
i. Transitive reference analyzer
6. Add template files
7. Update WCF service to CoreWCF (Preview)
8. Upgrade app config files
a. Convert Application Settings
b. Convert Connection Strings
c. Disable unsupported configuration sections
9. Update source code
a. Apply fix for UA0002: Types should be upgraded
b. Apply fix for UA0012: 'UnsafeDeserialize()' does not exist
c. Apply fix for UA0014: .NET MAUI projects should not reference Xamarin.Forms namespaces
d. Apply fix for UA0015: .NET MAUI projects should not reference Xamarin.Essentials namespaces
10. Move to next project
Choose a command:
1. Apply next step (Back up project)
2. Skip next step (Back up project)
3. See more step details
4. Select different project
5. Configure logging
6. Exit
Notes
Pour le reste de cet article, les étapes de mise à niveau ne sont pas montrées explicitement, sauf s’il y a quelque chose d’important à signaler. Les résultats de chaque étape sont néanmoins toujours affichés.
Création d'une sauvegarde
Dans cet exemple de mise à niveau du projet CalculatorService, vous allez appliquer chaque étape. La première étape, commande 1, consiste à sauvegarder le projet :
Output
[10:25:52 INF] Applying upgrade step Back up project
Please choose a backup path
1. Use default path [C:\Users\Desktop\CalculatorSample.backup]
2. Enter custom path
L’outil choisit un chemin de sauvegarde par défaut nommé d’après le dossier actif, mais y ajoute .backup. Vous pouvez choisir un chemin personnalisé comme alternative au chemin par défaut. Pour chaque projet mis à niveau, le dossier du projet est copié dans le dossier de sauvegarde. Dans cet exemple, le dossier CalculatorService est copié depuis CalculatorSample\CalculatorService vers CalculatorSample.backup\CalculatorService pendant l’étape de sauvegarde :
Output
[10:25:53 INF] Backing up C:\Users\Desktop\CalculatorSample\CalculatorService to C:\Users\OneDrive - Microsoft\Desktop\CalculatorSample.backup\CalculatorService
[10:25:53 INF] Project backed up to C:\Users\Desktop\CalculatorSample.backup\CalculatorService
[10:25:53 INF] Upgrade step Back up project applied successfully
Please press enter to continue...
Mettre à niveau le fichier projet
Le projet est mis à niveau du format de projet .NET Framework vers le format de projet SDK .NET.
Output
[10:25:56 INF] Applying upgrade step Convert project file to SDK style
[10:25:56 INF] Converting project file format with try-convert, version 0.4.0-dev
[10:25:56 INF] Recommending executable TFM net6.0 because the project builds to an executable
C:\Users\Desktop\CalculatorSample\CalculatorService\CalculatorService.csproj contains an App.config file. App.config is replaced by appsettings.json in .NET Core. You will need to delete App.config and migrate to appsettings.json if it's applicable to your project.
[10:25:58 INF] Converting project C:\Users\CalculatorSample\CalculatorService\CalculatorService.csproj to SDK style
[10:25:58 INF] Project file converted successfully! The project may require additional changes to build successfully against the new .NET target.
[10:26:00 INF] Upgrade step Convert project file to SDK style applied successfully
Faites attention à la sortie de chaque étape. Notez que l’exemple de sortie indique que vous devrez effectuer une étape manuelle après la mise à niveau :
App.config est remplacé par appsettings.json dans .NET Core. Vous devrez supprimer App.config et migrer vers appsettings.json si c’est applicable à votre projet.
Dans cet exemple, l’étape de mise à jour WCF va créer un fichier wcf.config basé sur la section system.serviceModel de App.config. Nous n’avons pas besoin de migrer vers appsettings.json.
Nettoyer les références NuGet
Une fois que le format du projet a été mis à jour, l’étape suivante consiste à nettoyer les références du package NuGet.
En plus des packages référencés par votre application, le fichier packages.config contient des références aux dépendances de ces packages. Par exemple, si vous avez ajouté une référence au package A qui dépend du package B, les deux packages sont référencés dans le fichier packages.config. Dans le nouveau système de projet, seule la référence au package A est nécessaire. Cette étape analyse les références de package et supprime celles qui ne sont pas nécessaires.
Votre application fait néanmoins toujours référence aux assemblys .NET Framework. Certains de ces assemblys peuvent être disponibles en tant que packages NuGet. Cette étape analyse ces assemblys et référence le package NuGet approprié.
Dans cet exemple, le programme de mise à jour de package détecte CalculatorService en tant que projet serveur uniquement et il n’est pas nécessaire d’ajouter des packages System.ServiceModel. Même si elles ont été ajoutées à la liste en fonction de la configuration du mappage des packages, ces étapes n’ont pas été appliquées.
Gérer le TFM
L’outil change ensuite le TFM et le fait passer de .NET Framework au SDK suggéré. Dans cet exemple, il s’agit de net6.0-windows.
Output
[10:26:17 INF] Applying upgrade step Update TFM
[10:26:17 INF] Recommending executable TFM net6.0 because the project builds to an executable
[10:26:19 INF] Updated TFM to net6.0
[10:26:19 INF] Upgrade step Update TFM applied successfully
Mettre à niveau des packages NuGet
Ensuite, l’outil met à jour les packages NuGet du projet vers les versions qui prennent en charge le TFM mis à jour, net6.0-windows.
Une fois les packages mis à jour, l’étape suivante consiste à mettre à jour les fichiers modèles. Dans cet exemple, aucun fichier modèle ne doit être mis à jour ou ajouté au projet. Cette étape est ignorée et l’étape suivante démarre automatiquement.
Mettre à jour le service WCF vers CoreWCF (préversion)
Remarque : Au moment de la rédaction de cette documentation, l’extension du programme de mise à jour WCF est fournie en tant que préversion. Si vous avez un feedback sur la préversion, ouvrez un problème dans le dépôt GitHub de l’Assistant Mise à niveau avec l’étiquette area:WCF.
L’Assistant Mise à niveau initialise d’abord l’étape Programme de mise à jour WCF et vérifie si le projet est applicable pour la mise à jour WCF.
Output
[10:26:20 INF] Initializing upgrade step Update WCF service to CoreWCF (Preview)
[10:26:20 INF] This config file is applicable for upgrade: C:\Users\Desktop\CalculatorSample\CalculatorService\App.config. System.serviceModel/services elements were found.
[10:26:20 INF] This file is applicable for upgrade: C:\Users\Desktop\CalculatorSample\CalculatorService\service.cs. ServiceHost object was found.
[10:26:20 INF] This project file is applicable for upgrade: C:\Users\Desktop\CalculatorSample\CalculatorService\CalculatorService.csproj. Reference to System.serviceModel was found.
[10:26:20 INF] This project is applicable for updating to CoreWCF. Initializing the update step...
[10:26:20 INF] Updaters are successfully constructed. Ready to start update.
Choose a command:
1. Apply next step (Update WCF service to CoreWCF (Preview))
2. Skip next step (Update WCF service to CoreWCF (Preview))
3. See more step details
4. Select different project
5. Configure logging
6. Exit
L’étape vérifie le fichier de configuration, le code source et le fichier projet séparément pour déterminer si la mise à jour WCF est applicable au projet. Si ce n’est pas applicable pour le projet (par exemple si vous n’utilisez pas WCF ou que ne satisfaites pas aux exigences énoncées au début de l’article), le message de journalisation décrit le fichier pour lequel ce n’est pas applicable et ce qui est manquant. Ensuite, l’étape est ignorée et l’étape suivante est démarrée automatiquement.
Dans cet exemple, la mise à jour WCF est applicable pour CalculatorSample et nous allons choisir la commande 1 pour appliquer l’étape.
Output
[10:26:23 INF] Applying upgrade step Update WCF service to CoreWCF (Preview)
[10:26:23 INF] Finish updating project file.
[10:26:23 WRN] The mex endpoint is removed from .config file, and service metadata behavior is configured in the source code instead.
[10:26:23 INF] Finish updating configuration files.
[10:26:23 WRN] Changing void Main() to async Task Main() to enable awaiting starting and stopping the ASP.NET Core host.
[10:26:23 INF] Finish updating source code.
[10:26:23 INF] Finish writing changes to project file.
[10:26:23 INF] Finish writing changes to configuration files.
[10:26:23 INF] Finish writing changes to the source code to replace the ServiceHost instance(s).
[10:26:23 INF] Project was successfully updated to use CoreWCF services. Please review changes.
[10:26:23 INF] Upgrade step Update WCF service to CoreWCF (Preview) applied successfully
Cette étape crée les mises à jour et les écrit individuellement dans les fichiers d’origine. Faites attention à la sortie, qui peut vous avertir de la suppression des fichiers d’origine ou des mises à jour manuelles à effectuer après la mise à niveau.
Mise à jour des fichiers de configuration et de code
Ces étapes peuvent être ignorées automatiquement par l’outil s’il détermine qu’il n’y a rien à faire pour votre projet.
Une fois la mise à jour WCF terminée, l’étape suivante consiste à mettre à jour les fichiers de configuration de l’application. Dans cet exemple, il n’y a rien à mettre à niveau dans les fichiers de configuration de l’application. L’étape WCF a déjà mis à jour les fichiers de configuration : cette étape ne signale donc rien sur l’utilisation du system.serviceModel non pris en charge. Cette étape est ignorée et l’étape suivante démarre automatiquement.
Output
[10:26:43 INF] Initializing upgrade step Upgrade app config files
[10:26:43 INF] Found 0 app settings for upgrade:
[10:26:43 INF] Found 0 connection strings for upgrade:
[10:26:43 INF] 0 web page namespace imports need upgraded:
La dernière étape avant la fin de la mise à niveau de ce projet consiste à mettre à jour toutes les références de code obsolètes. En fonction du type de projet que vous mettez à niveau, une liste de correctifs de code connus est affichée pour cette étape. Certains des correctifs peuvent ne pas s’appliquer à votre projet.
Output
9. Update source code
a. Apply fix for UA0002: Types should be upgraded
b. Apply fix for UA0012: 'UnsafeDeserialize()' does not exist
c. Apply fix for UA0014: .NET MAUI projects should not reference Xamarin.Forms namespaces
d. Apply fix for UA0015: .NET MAUI projects should not reference Xamarin.Essentials namespaces
Dans le cas présent, aucun des correctifs suggérés ne s’applique à l’exemple de projet, et cette étape se termine automatiquement immédiatement après la fin de l’étape précédente.
Output
[10:26:44 INF] Initializing upgrade step Update source code
[10:26:44 INF] Running analyzers on CalculatorService
[10:26:48 INF] Identified 0 diagnostics in project CalculatorService
[10:26:51 INF] Initializing upgrade step Move to next project
Réalisation de la mise à niveau
S’il existe d’autres projets à migrer, l’outil vous permet de sélectionner le projet suivant à mettre à niveau. Quand il n’y a plus de projets à mettre à niveau, l’outil vous amène à l’étape « Finaliser la mise à niveau » :
Output
1. [Next step] Finalize upgrade
Choose a command:
1. Apply next step (Finalize upgrade)
2. Skip next step (Finalize upgrade)
3. See more step details
4. Configure logging
5. Exit
>
[10:27:15 INF] Applying upgrade step Finalize upgrade
[10:27:15 INF] Upgrade step Finalize upgrade applied successfully
Dans l’idéal, après la réussite de l’exécution de l’outil, ces modifications doivent apparaître dans les fichiers d’origine.
Dans le fichier service.cs, le using System.ServiceModel a été remplacé par des références à CoreWCF. L’instance ServiceHost a également été supprimée et le service a été hébergé sur ASP.NET Core.
C#
using System;
using System.Threading.Tasks;
using CoreWCF;
using CoreWCF.Configuration;
using CoreWCF.Description;
using CoreWCF.Security;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
C#
publicstaticasync Task Main()
{
var builder = WebApplication.CreateBuilder();
// Set up port (previously this was done in configuration,// but CoreWCF requires it be done in code)
builder.WebHost.UseNetTcp(8090);
builder.WebHost.ConfigureKestrel(options =>
{
options.ListenAnyIP(8080);
});
// Add CoreWCF services to the ASP.NET Core app's DI container
builder.Services.AddServiceModelServices()
.AddServiceModelConfigurationManagerFile("wcf.config")
.AddServiceModelMetadata()
.AddTransient<CalculatorSample.CalculatorService>();
var app = builder.Build();
// Enable getting metadata/wsdlvar serviceMetadataBehavior = app.Services.GetRequiredService<ServiceMetadataBehavior>();
serviceMetadataBehavior.HttpGetEnabled = true;
serviceMetadataBehavior.HttpGetUrl = new Uri("http://localhost:8080/CalculatorSample/metadata");
// Configure CoreWCF endpoints in the ASP.NET Core hosts
app.UseServiceModel(serviceBuilder =>
{
serviceBuilder.AddService<CalculatorSample.CalculatorService>(serviceOptions =>
{
serviceOptions.DebugBehavior.IncludeExceptionDetailInFaults = true;
});
serviceBuilder.ConfigureServiceHostBase<CalculatorSample.CalculatorService>(serviceHost =>
{
});
});
await app.StartAsync();
Console.WriteLine("The service is ready.");
Console.WriteLine("Press <ENTER> to terminate service.");
Console.WriteLine();
Console.ReadLine();
await app.StopAsync();
}
Pour les fichiers de configuration, la section system.serviceModel dans App.config a été déplacée vers le nouveau fichier de configuration wcf.config, qui a été généré pendant la mise à jour.
App.config
XML
<?xml version="1.0" encoding="utf-8"?><configuration><!-- system.serviceModel section is moved to a separate wcf.config file located at the same directory as this file.--></configuration>
wcf.config
XML
<?xml version="1.0" encoding="utf-8"?><configuration><system.serviceModel><services><servicename="CalculatorSample.CalculatorService"behaviorConfiguration="CalculatorServiceBehavior"><!--The host element is not supported in configuration in CoreWCF. The port that endpoints listen on is instead configured in the source code.--><!--<host>
<baseAddresses>
<add baseAddress="net.tcp://localhost:8090/CalculatorSample/service" />
<add baseAddress="http://localhost:8080/CalculatorSample/service" />
</baseAddresses>
</host>--><!-- this endpoint is exposed at the base address provided by host: net.tcp://localhost:8090/CalculatorSample/service --><endpointaddress="/CalculatorSample/service"binding="netTcpBinding"contract="CalculatorSample.ICalculator" /><!-- the mex endpoint is exposed at http://localhost:8080/CalculatorSample/service/ --><!--The mex endpoint is removed because it's not support in CoreWCF. Instead, the metadata service is enabled in the source code.--></service></services><!--For debugging purposes set the includeExceptionDetailInFaults attribute to true--><!--The behavior element is not supported in configuration in CoreWCF. Some service behaviors, such as metadata, are configured in the source code.--><!--<behaviors>
<serviceBehaviors>
<behavior name="CalculatorServiceBehavior">
<serviceMetadata httpGetEnabled="True" />
<serviceDebug includeExceptionDetailInFaults="True" />
</behavior>
</serviceBehaviors>
</behaviors>--></system.serviceModel></configuration>
Enfin, dans le fichier projet, CalculatorService.csproj, le SDK a été mis à jour vers Microsoft.NET.Sdk.Web pour activer l’hôte ASP.NET Core et les références de package CoreWCF ont été ajoutées.
Notez que dans CalculatorSample, il n’existe pas de dépendance de projet à projet et que l’exemple peut s’exécuter correctement seulement après la mise à jour de CalculatorService. Dans d’autres cas avec des dépendances différentes, vous devrez néanmoins peut-être aussi mettre à jour d’autres projets de la même solution.
Après la mise à niveau
Après avoir mis à niveau vos projets, vous devez les compiler et les tester. L’Assistant Mise à niveau va faire ce qu’il peut, mais il ne peut pas résoudre toutes les incompatibilités dans le cadre de la mise à niveau du projet. Par exemple, il est possible que la version .NET Framework de votre application contienne des références de bibliothèque que votre projet n’utilise pas. Vous devez analyser chaque référence et déterminer si elle est nécessaire ou non. L’outil a peut-être aussi ajouté ou mis à niveau une référence de package NuGet vers une version incorrecte.
Conseils de dépannage
Plusieurs problèmes connus peuvent se produire lors de l’utilisation de l’Assistant Mise à niveau de .NET. Dans certains cas, il s’agit de problèmes avec l’outil try-convert que l’Assistant Mise à niveau de .NET utilise en interne.
La source de ce contenu se trouve sur GitHub, où vous pouvez également créer et examiner les problèmes et les demandes de tirage. Pour plus d’informations, consultez notre guide du contributeur.
Commentaires sur .NET
.NET est un projet open source. Sélectionnez un lien pour fournir des commentaires :
Dans ce module, vous apprendrez quand, pourquoi et comment moderniser une application ASP.NET Framework vers ASP.NET Core à l’aide de l’Assistant Mise à niveau.