Générer un fichier texte de l'API publique de la bibliothèque .NET pour le suivi des versions et de la compatibilité.

Question

Je maintiens beaucoup trop de paquets NuGet et j'essaie de trouver un outil qui génère un fichier texte brut de la surface API publique pour chaque assemblage (comme une étape post-construction). Chaque espace de nom, classe, interface, structure, signature de méthode, membre, champ, serait une ligne, le tout trié par ordre alphabétique.

Avoir un src/PublicAPIs.txt La modification du fichier à chaque fois que je modifie la surface de l'API publique serait extraordinaire - le diff de github me montrerait immédiatement ce que j'ai modifié, supprimé ou ajouté, et le fichier serait inestimable pour suivre les modifications de l'API au fil du temps.

Je serais beaucoup moins susceptible d'exposer accidentellement une API privée ou de casser une API existante, je pense.

J'ai l'impression que cela doit déjà exister et que je rate quelque chose ? Je connais Telerik JustAssembly pour les comparaisons basiques de .dll, mais je cherche quelque chose qui puisse écrire un fichier dans le dépôt git automatiquement, de sorte que je n'aie pas à me rappeler d'ouvrir un outil, et que tout changement de rupture apparaisse pendant mon flux de travail normal.

Answer 1

Microsoft a quelques outils qui pourraient être utiles ici : Microsoft.DotNet.ApiCompat y Microsoft.CodeAnalysis.PublicApiAnalyzers .

Analyseurs Microsoft.CodeAnalysis.PublicApiAnalyzers

Incluant une référence de paquet pour Analyseurs Microsoft.CodeAnalysis.PublicApiAnalyzers permettra de générer des fichiers texte qui faciliteront l'identification des changements de rupture dans vos API.

OpenTelemetry propose un exemple d'utilisation de la fonction différents fichiers texte pour différents cadres cibles

Microsoft.DotNet.ApiCompat

ApiCompat peut également être utilisé pour tester la compatibilité API entre deux assemblages .NET.

Malheureusement, ce projet n'est pas sur nuget.org mais il est utilisé en dehors d'une variété de projets Microsoft par les entreprises suivantes au moins Automapper y OpenTelemetry .

Voici un article de blog qui fournit une bonne description de l'ajout du paquet, que je vais résumer brièvement sans essayer de reproduire une grande partie du contenu :

1. Ajouter Flux nuget des outils .NET Core à votre fichier nuget.config
2. Ajouter une référence de paquet pour "Microsoft.DotNet.ApiCompat".
3. Ajouter une référence à une copie de la version majeure précédente de l'assemblage (ou utiliser un script pour l'obtenir)

La configuration par défaut devrait aboutir à un build cassé lorsque vous effectuez des changements cassants, mais vous pouvez modifier ce comportement grâce à l'option paramètres supplémentaires comme BaselineAllAPICompatError qui sont disponibles, comme l'a fait Automapper

Answer 2

Vous devez tenir compte de la PublicApiGenerator Paquet NuGet pour cela.

Il fournit un moyen très simple de générer un string qui contient votre API publique à partir d'un ou plusieurs assemblages.

L'exemple suivant (extrait du README du projet) montre comment vous pouvez utiliser le paquetage pour créer un test unitaire qui échouera lorsque l'API publique aura été modifiée :

[Fact]
public void my_assembly_has_no_public_api_changes()
{
    var publicApi = typeof(Library).Assembly.GeneratePublicApi();

    var approvedFilePath = "PublicApi.approved.txt";
    if (!File.Exists(approvedFilePath))
    {
        // Create a file to write to.
        using (var sw = File.CreateText(approvedFilePath)) { }
    }

    var approvedApi = File.ReadAllText(approvedFilePath);

    Assert.Equal(approvedApi, publicApi);
}

Le test ci-dessus vous obligera à régénérer l'API approuvée en cas de modifications importantes, de sorte que les modifications importantes seront une décision consciente.

Answer 3

Si j'ai bien compris, vous voulez simplement vérifier si l'API a subi des modifications importantes et en avertir les utilisateurs. Je recommanderais d'utiliser swagger pour vos API afin qu'il soit facile d'explorer les API. Mais il peut également être utilisé pour vérifier / tester les changements de rupture :

https://swagger.io/blog/api-development/using-swagger-to-detect-breaking-api-changes/

eg :

$ gem install swagger-diff
$ wget https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-minimal.json

$ wget https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-expanded.json

$ swagger-diff petstore-minimal.json petstore-expanded.json

Il suffit donc d'enregistrer le fichier swagger lors de la construction.

eg : https://medium.com/@woeterman_94/how-to-generate-a-swagger-json-file-on-build-in-net-core-fa74eec3df1

Si vous n'utilisez pas déjà swagger : https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-6.0

J'espère que cela vous aidera :)

Answer 4

Pour satisfaire à ces exigences de suivi du contenu des DLL, vous devrez développer une application console qui devra être invoquée dans l'étape de post-construction et qui devra contenir les routines suivantes :

Pour lire les DLL gérées, vous pouvez suivre les approches suivantes : Méthode Assembly.LoadFrom o Utilisation de Reflection pour charger des assemblages non référencés au moment de l'exécution en C#

Pour lire les DLLs non gérées : Invocation de la plate-forme (P/Invoke) o PInvoke.net

Dans la même application console, après avoir lu le contenu des DLL, vous pouvez écrire ce contenu en utilisant cette approche : Comment écrire dans un fichier texte (Guide de programmation C#)

Je pense que c'est tout.

Answer 5

ILSpyCmd est le plus proche que je puisse trouver qui

1. Est un outil CLI pour une intégration facile après la construction.
2. Il y a une option pour abandonner certaines des entités que vous voulez :

-l|--list <entity-type(s)> Lists all entities of the specified type(s). Valid types: c(lass), i(nterface), s(truct), d(elegate), e(num)

3. Est un paquet nuget . Cependant, il est installé via dotnet tool install -g qui devrait être un peu différent de ce que vous attendez.

Le résultat ressemble à ceci :

Et comme vous pouvez le voir, il manque encore quelques informations détaillées telles que les méthodes et les champs d'une classe, mais tous les détails (signatures de méthodes, membres d'énumérations, etc.) devraient déjà être décompilés dans le fichier d'aide à la décision. decompiler objet dans ListContent() méthode de IlspyCmdProgram.cs . Vous pouvez cloner les dépôts, puis ajouter quelques lignes pour les parcourir et les imprimer dans le format de votre choix.