Développer des fonctions .NET Standard définies par l’utilisateur pour des travaux Azure Stream Analytics (préversion)Develop .NET Standard user-defined functions for Azure Stream Analytics jobs (Preview)

Azure Stream Analytics offre un langage de requête de type SQL pour effectuer des transformations et des calculs sur des flux de données d’événement.Azure Stream Analytics offers a SQL-like query language for performing transformations and computations over streams of event data. De nombreuses fonctions sont intégrées, mais certains scénarios complexes nécessitent davantage de flexibilité.There are many built-in functions, but some complex scenarios require additional flexibility. Avec les fonctions .NET Standard définies par l’utilisateur, vous pouvez appeler vos propres fonctions écrites dans n’importe quel langage .NET Standard (C#, F#, etc.) pour étendre le langage de requête Stream Analytics.With .NET Standard user-defined functions (UDF), you can invoke your own functions written in any .NET standard language (C#, F#, etc.) to extend the Stream Analytics query language. Les fonctions définies par l’utilisateur vous permettent d’effectuer des calculs mathématiques complexes, d’importer des modèles Machine Learning personnalisés à l’aide de ML.NET et d’utiliser une logique personnalisée d’imputation pour les données manquantes.UDFs allow you to perform complex math computations, import custom ML models using ML.NET, and use custom imputation logic for missing data. La fonctionnalité de fonction définie par l’utilisateur pour les travaux Stream Analytics est actuellement disponible en préversion et ne doit pas être utilisée dans des charges de travail de production.The UDF feature for Stream Analytics jobs is currently in preview and shouldn't be used in production workloads.

La fonction .NET définie par l’utilisateur pour les travaux cloud est disponible dans les régions suivantes :.NET user-defined-function for cloud jobs is available in:

  • Centre-USA OuestWest Central US
  • Europe NordNorth Europe
  • USA EstEast US
  • USA OuestWest US
  • USA Est 2East US 2
  • Europe OuestWest Europe

Si vous êtes intéressé par l’utilisation de cette fonctionnalité dans une autre région, vous pouvez demander l’accès.If you are interested in using this feature in any another region, you can request access.

Chemin du packagePackage path

Le format d’un package de fonction définie par l’utilisateur a le chemin /UserCustomCode/CLR/*.The format of any UDF package has the path /UserCustomCode/CLR/*. Les bibliothèques de liens dynamiques (DLL) et les ressources sont copiées sous le dossier /UserCustomCode/CLR/*, qui permet d’isoler les DLL utilisateur du système et les DLL Azure Stream Analytics.Dynamic Link Libraries (DLLs) and resources are copied under the /UserCustomCode/CLR/* folder, which helps isolate user DLLs from system and Azure Stream Analytics DLLs. Ce chemin du package est utilisé pour toutes les fonctions, quelle que soit la méthode d’utilisation choisie.This package path is used for all functions regardless of the method used to employ them.

Types pris en charge et mappageSupported types and mapping

Pour que les valeurs Azure Stream Analytics puissent être utilisées en C#, elles doivent être marshalées d’un environnement à l’autre.For Azure Stream Analytics values to be used in C#, they need to be marshaled from one environment to the other. Le marshaling se produit pour tous les paramètres en entrée d’une fonction définie par l’utilisateur.Marshaling happens for all input parameters of a UDF. Chaque type Azure Stream Analytics a un type correspondant en C#, indiqué dans le tableau ci-dessous :Every Azure Stream Analytics type has a corresponding type in C# shown on the table below:

Type Azure Stream AnalyticsAzure Stream Analytics type Type C#C# type
bigintbigint longlong
floatfloat doubledouble
nvarchar(max)nvarchar(max) stringstring
DATETIMEdatetime DateTimeDateTime
EnregistrementRecord Dictionnaire<string, object>Dictionary<string, object>
ArrayArray Object[]Object[]

Il en va de même lorsque les données doivent être marshalées de C# vers Azure Stream Analytics, ce qui se produit sur la valeur de sortie d’une fonction définie par l’utilisateur.The same is true when data needs to be marshaled from C# to Azure Stream Analytics, which happens on the output value of a UDF. Le tableau ci-dessous montre les types pris en charge :The table below shows what types are supported:

Type C#C# type Type Azure Stream AnalyticsAzure Stream Analytics type
longlong bigintbigint
doubledouble floatfloat
stringstring nvarchar(max)nvarchar(max)
DateTimeDateTime dateTimedateTime
structstruct EnregistrementRecord
objectobject EnregistrementRecord
Object[]Object[] ArrayArray
Dictionnaire<string, object>Dictionary<string, object> EnregistrementRecord

Développez une UDF dans Visual Studio CodeDevelop a UDF in Visual Studio Code

Les outils Visual Studio Code pour Azure Stream Analytics vous facilite l’écriture de fonctions définies par l’utilisateur, le test de vos travaux localement (même en mode hors connexion) et la publication de votre travail Stream Analytics dans Azure.Visual Studio Code tools for Azure Stream Analytics make it easy for you to write UDFs, test your jobs locally (even offline), and publish your Stream Analytics job to Azure.

Il existe deux façons d’implémenter des fonctions définies par l’utilisateur .NET Standard dans des outils Visual Studio Code.There are two ways to implement .NET standard UDFs in Visual Studio Code tools.

  • UDF des bibliothèques de liens dynamiques localesUDF from local DLLs
  • Fonction définie par l’utilisateur à partir d’un projet localUDF from a local project

Projet localLocal project

Les fonctions définies par l’utilisateur peuvent être écrites dans un assembly référencé plus tard dans une requête Azure Stream Analytics.User-defined functions can be written in an assembly that is later referenced in an Azure Stream Analytics query. Il s’agit de l’option recommandée pour les fonctions complexes qui nécessitent toute la puissance d’un langage .NET Standard au-delà de son langage d’expression, comme la logique procédurale ou la récursivité.This is the recommended option for complex functions that require the full power of a .NET Standard language beyond its expression language, such as procedural logic or recursion. Les fonctions définies par l’utilisateur à partir d’un projet local peuvent également être utilisées si vous avez besoin de partager la logique de la fonction entre plusieurs requêtes Azure Stream Analytics.UDFs from a local project might also be used when you need to share the function logic across several Azure Stream Analytics queries. L’ajout de fonctions définies par l’utilisateur à votre projet local vous donne la possibilité de déboguer et de tester vos fonctions localement.Adding UDFs to your local project gives you the ability to debug and test your functions locally.

Pour référencer un projet local :To reference a local project:

  1. Créez une nouvelle bibliothèque de classes .NET Standard sur votre ordinateur local.Create a new .NET standard class library on your local machine.
  2. Écrivez le code dans votre classe.Write the code in your class. Toutes les classes doivent être définies comme étant publiques et tous les objets comme étant publics statiques.Remember that the classes must be defined as public and objects must be defined as static public.
  3. Ajoutez un nouveau fichier de configuration de fonction CSharp dans votre projet Azure Stream Analytics, et référencez le projet de bibliothèque de classes CSharp.Add a new CSharp Function configuration file in your Azure Stream Analytics project and reference the CSharp class library project.
  4. Configurez le chemin de l’assembly dans le fichier de configuration du travail JobConfig.json, section CustomCodeStorage. Cette étape n’est pas nécessaire pour les tests locaux.Configure the assembly path in the job configuration file, JobConfig.json, CustomCodeStorage section.This step is not needed for local testing.

Bibliothèques de liens dynamiques localesLocal DLLs

Vous pouvez également référencer des bibliothèques de liens dynamiques locales qui incluent les fonctions définies par l’utilisateur.You can also reference local DLLs that include the user-defined functions.

ExempleExample

Dans cet exemple, CSharpUDFProject est un projet de bibliothèque de classes C# et ASAUDFDemo est le projet Azure Stream Analytics qui référence CSharpUDFProject.In this example, CSharpUDFProject is a C# class library project and ASAUDFDemo is the Azure Stream Analytics project, which will reference CSharpUDFProject.

Projet Azure Stream Analytics dans Visual Studio Code

La fonction définie par l’utilisateur suivante a une fonction qui multiplie un entier par lui-même pour produire le carré de l’entier.The following UDF has a function that multiplies an integer by itself to produce the square of the integer. Les classes doivent être définies en tant que classes publiques et les objets doivent être définis en tant qu’objets publics statiques.The classes must be defined as public and objects must be defined as static public.

using System;

namespace CSharpUDFProject
{
    // 
    public class Class1
    {
        public static Int64 SquareFunction(Int64 a)
        {
            return a * a;
        }
    }
}

Les étapes suivantes vous montrent comment ajouter la fonction UDF C# à votre projet Stream Analytics.The following steps show you how to add C# UDF function to your Stream Analytics project.

  1. Cliquez avec le bouton droit sur le dossier Fonctions et choisissez Ajouter un élément.Right click on the Functions folder and choose Add Item.

    Ajoutez une nouvelle fonction dans le projet Azure Stream Analytics

  2. Ajoutez une fonction C# SquareFunction à votre projet Azure Stream Analytics.Add a C# function SquareFunction to your Azure Stream Analytics project.

    Sélectionner la fonction CSharp dans le projet Stream Analytics en VS Code

    Entrez le nom de la fonction CSharp dans VS Code

  3. Dans la configuration de la fonction C#, sélectionnez Sélectionner le chemin d’accès au projet de bibliothèque pour choisir votre projet C# dans la liste déroulante et sélectionnez Projet build pour générer votre projet.In the C# function configuration, select Choose library project path to choose your C# project from the dropdown list and select Build project to build your project. Choisissez ensuite Sélectionner une classe et Sélectionner la méthode pour sélectionner le nom de la classe et de la méthode associée dans la liste déroulante.Then choose Select class and Select method to select the related class and method name from the dropdown list. Pour référencer les méthodes, types et fonctions dans la requête Stream Analytics, les classes doivent être définies comme étant publiques et les objets comme étant publics statiques.To refer to the methods, types, and functions in the Stream Analytics query, the classes must be defined as public and the objects must be defined as static public.

    Fonction Stream Analytics CSharp configuration VS Code

    Si vous souhaitez utiliser C# UDF à partir d’une DLL, sélectionnez Choisir le chemin d’accès à la DLL de la bibliothèque pour choisir la DLL.If you want to use the C# UDF from a DLL, select Choose library dll path to choose the DLL. Choisissez ensuite Sélectionner une classe et Sélectionner la méthode pour sélectionner le nom de la classe et de la méthode associée dans la liste déroulante.Then choose Select class and Select method to select the related class and method name from the dropdown list.

    Configuration de la fonction C Sharp dans Stream Analytics

  4. Appelez l’UDF dans votre requête Azure Stream Analytics.Invoke the UDF in your Azure Stream Analytics query.

     SELECT price, udf.SquareFunction(price)
     INTO Output
     FROM Input 
    
  5. Avant de soumettre la tâche à Azure, configurez le chemin d’accès au package dans le fichier de configuration du travail, JobConfig.json, section CustomCodeStorage.Before submitting the job to Azure, configure the package path in the job configuration file, JobConfig.json, CustomCodeStorage section. Utilisez Sélectionner votre abonnement dans CodeLens pour choisir votre abonnement et choisissez le compte de stockage et le nom du conteneur dans la liste déroulante.Use Select from your subscription in CodeLens to choose your Subscription and choose the storage account and container name from the dropdown list. Laissez Chemin d’accès par défaut.Leave Path as default. Cette étape n’est pas nécessaire pour les tests locaux.This step is not needed for local testing.

    Choisir le chemin de la bibliothèque

Développez une UDF dans Visual Studio CodeDevelop a UDF in Visual Studio

Il existe trois façons d’implémenter dans des outils Visual Studio.There are three ways to implement UDFs in Visual Studio tools.

  • Fichiers code-behind dans un projet ASACodeBehind files in an ASA project
  • Fonction définie par l’utilisateur à partir d’un projet localUDF from a local project
  • Package existant à partir d’un compte de stockage AzureAn existing package from an Azure storage account

CodeBehindCodeBehind

Vous pouvez écrire des fonctions définies par l’utilisateur dans le fichier code-behind Script.asql.You can write user-defined functions in the Script.asql CodeBehind. Les outils Visual Studio compilent automatiquement le fichier code-behind dans un fichier d’assembly.Visual Studio tools will automatically compile the CodeBehind file into an assembly file. Les assemblys sont packagés dans un fichier zip et chargés dans votre compte de stockage quand vous envoyez votre travail à Azure.The assemblies are packaged as a zip file and uploaded to your storage account when you submit your job to Azure. Vous pouvez apprendre à écrire une fonction C# définie par l’utilisateur à l’aide de d’un fichier code-behind en suivant le tutoriel Fonction C# définie par l’utilisateur pour les travaux de périphérie Stream Analytics.You can learn how to write a C# UDF using CodeBehind by following the C# UDF for Stream Analytics Edge jobs tutorial.

Projet localLocal project

Pour référencer un projet local dans Visual Studio :To reference a local project in Visual Studio:

  1. Créez une nouvelle bibliothèque de classes .NET Standard dans votre solutionCreate a new .NET standard class library in your solution
  2. Écrivez le code dans votre classe.Write the code in your class. Toutes les classes doivent être définies comme étant publiques et tous les objets comme étant publics statiques.Remember that the classes must be defined as public and objects must be defined as static public.
  3. Générez votre projet.Build your project. Les outils créent un fichier zip contenant tous les artefacts du dossier bin, puis chargent ce fichier zip dans le compte de stockage.The tools will package all the artifacts in the bin folder to a zip file and upload the zip file to the storage account. Pour les références externes, utilisez la référence d’assembly au lieu du package NuGet.For external references, use assembly reference instead of the NuGet package.
  4. Référencez la nouvelle classe dans votre projet Azure Stream Analytics.Reference the new class in your Azure Stream Analytics project.
  5. Ajoutez une nouvelle fonction dans votre projet Azure Stream Analytics.Add a new function in your Azure Stream Analytics project.
  6. Configurez le chemin d’assembly dans le fichier de configuration du travail, JobConfig.json.Configure the assembly path in the job configuration file, JobConfig.json. Définissez le chemin d’assembly sur Référence de projet locale ou code-behind.Set the Assembly Path to Local Project Reference or CodeBehind.
  7. Regénérez le projet de fonction et le projet Azure Stream Analytics.Rebuild both the function project and the Azure Stream Analytics project.

ExempleExample

Dans cet exemple, UDFTest est un projet de bibliothèque de classes C# et ASAUDFDemo est le projet Azure Stream Analytics qui référence UDFTest.In this example, UDFTest is a C# class library project and ASAUDFDemo is the Azure Stream Analytics project, which will reference UDFTest.

Projet IoT Edge Azure Stream Analytics dans Visual Studio

  1. Générez votre projet C# pour pouvoir ajouter une référence à votre fonction C# définie par l’utilisateur à partir de la requête Azure Stream Analytics.Build your C# project, which will enable you to add a reference to your C# UDF from the Azure Stream Analytics query.

    Générer un projet Iot Edge Azure Stream Analytics dans Visual Studio

  2. Ajoutez la référence au projet C# dans le projet ASA.Add the reference to the C# project in the ASA project. Cliquez avec le bouton droit sur le nœud Références et choisissez Ajouter une référence.Right-click the References node and choose Add Reference.

    Ajouter une référence à un projet C# dans Visual Studio

  3. Choisissez le nom du projet C# dans la liste.Choose the C# project name from the list.

    Choisissez le nom de votre projet C# dans la liste de référence

  4. Vous devez voir UDFTest listé sous Références dans l’Explorateur de solutions.You should see the UDFTest listed under References in Solution Explorer.

    Afficher la référence de la fonction définie par l’utilisateur dans l’Explorateur de solutions

  5. Cliquez avec le bouton droit sur le dossier Fonctions et choisissez Nouvel élément.Right click on the Functions folder and choose New Item.

    Ajouter un nouvel élément au dossier Fonctions dans la solution de périphérie Azure Stream Analytics

  6. Ajoutez une fonction C# SquareFunction.json à votre projet Azure Stream Analytics.Add a C# function SquareFunction.json to your Azure Stream Analytics project.

    Sélectionner la fonction C Sharp parmi les éléments de périphérie Stream Analytics dans Visual Studio

  7. Double-cliquez sur la fonction dans l’Explorateur de solutions pour ouvrir la boîte de dialogue de configuration.Double-click the function in Solution Explorer to open the configuration dialog.

    Configuration de la fonction C Sharp dans Visual Studio

  8. Dans la configuration de fonction C#, choisissez Charger à partir d’une référence de projet ASA ainsi que les noms des assemblys, classes et méthodes associés dans la liste déroulante.In the C# function configuration, choose Load from ASA Project Reference and the related assembly, class, and method names from the dropdown list. Pour référencer les méthodes, types et fonctions dans la requête Stream Analytics, les classes doivent être définies comme étant publiques et les objets comme étant publics statiques.To refer to the methods, types, and functions in the Stream Analytics query, the classes must be defined as public and the objects must be defined as static public.

    Fonction Stream Analytics C sharp configuration Visual Studio

Packages existantsExisting packages

Vous pouvez créer des fonctions définies par l’utilisateur .NET Standard dans l’IDE de votre choix et les appeler à partir de votre requête Azure Stream Analytics.You can author .NET Standard UDFs in any IDE of your choice and invoke them from your Azure Stream Analytics query. Commencez par compiler votre code et packager toutes les DLL.First compile your code and package all the DLLs. Le format du package a le chemin /UserCustomCode/CLR/*.The format of the package has the path /UserCustomCode/CLR/*. Ensuite, chargez UserCustomCode.zip à la racine du conteneur dans votre compte de stockage Azure.Then, upload UserCustomCode.zip to the root of the container in your Azure storage account.

Une fois les packages zip d’assemblys chargés dans votre compte de stockage Azure, vous pouvez utiliser les fonctions dans des requêtes Azure Stream Analytics.Once assembly zip packages have been uploaded to your Azure storage account, you can use the functions in Azure Stream Analytics queries. Il vous suffit d’inclure les informations de stockage dans la configuration du travail Stream Analytics.All you need to do is include the storage information in the Stream Analytics job configuration. Vous ne pouvez pas tester la fonction localement à l’aide de cette option, car les outils Visual Studio ne téléchargent pas votre package.You can't test the function locally with this option because Visual Studio tools will not download your package. Le chemin du package est analysé directement par le service.The package path is parsed directly to the service.

Pour configurer le chemin d’assembly dans le fichier de configuration du travail, JobConfig.json :To configure the assembly path in the job configuration file, JobConfig.json:

Développez la section Configuration du code défini par l’utilisateur et remplissez la configuration avec les valeurs suggérées suivantes :Expand the User-Defined Code Configuration section, and fill out the configuration with the following suggested values:

ParamètreSetting Valeur suggéréeSuggested Value
Ressource des paramètres de stockage générauxGlobal Storage Settings Resource Choisir une source de données du compte actuelChoose data source from current account
Abonnement des paramètres de stockage générauxGlobal Storage Settings Subscription < votre abonnement >< your subscription >
Compte de stockage des paramètres de stockage générauxGlobal Storage Settings Storage Account < votre compte de stockage >< your storage account >
Ressource des paramètres de stockage de code personnaliséCustom Code Storage Settings Resource Choisir une source de données du compte actuelChoose data source from current account
Compte de stockage des paramètres de stockage de code personnaliséCustom Code Storage Settings Storage Account < votre compte de stockage >< your storage account >
Conteneur des paramètres de stockage de code personnaliséCustom Code Storage Settings Container < votre conteneur de stockage >< your storage container >
Source de l’assembly de code personnaliséCustom Code Assembly Source Packages d’assembly existants du cloudExisting assembly packages from the cloud
Source de l’assembly de code personnaliséCustom Code Assembly Source UserCustomCode.zipUserCustomCode.zip

Journalisation utilisateurUser logging

Le mécanisme de journalisation vous permet de capturer des informations personnalisées pendant l’exécution d’un travail.The logging mechanism allows you to capture custom information while a job is running. Vous pouvez utiliser les données de journal pour déboguer ou évaluer l’exactitude du code personnalisé en temps réel.You can use log data to debug or assess the correctness of the custom code in real time.

La classe StreamingContext vous permet de publier des informations de diagnostic à l’aide de la fonction StreamingDiagnostics.WriteError.The StreamingContext class lets you publish diagnostic information using the StreamingDiagnostics.WriteError function. Le code ci-dessous montre l’interface exposée par Azure Stream Analytics.The code below shows the interface exposed by Azure Stream Analytics.

public abstract class StreamingContext
{
    public abstract StreamingDiagnostics Diagnostics { get; }
}

public abstract class StreamingDiagnostics
{
    public abstract void WriteError(string briefMessage, string detailedMessage);
}

StreamingContext est transmis à la méthode UDF en tant que paramètre d’entrée et peut être utilisé dans l’UDF pour publier des informations de journal personnalisées.StreamingContext is passed as an input parameter to the UDF method and can be used within the UDF to publish custom log information. Dans l’exemple ci-dessous, MyUdfMethod définit une entrée de données, fournie par la requête, et un contexte d’entrée en tant que StreamingContext, fourni par le moteur d’exécution.In the example below, MyUdfMethod defines a data input, which is provided by the query, and a context input as the StreamingContext, provided by the runtime engine.

public static long MyUdfMethod(long data, StreamingContext context)
{
    // write log
    context.Diagnostics.WriteError("User Log", "This is a log message");
    
    return data;
}

La valeur StreamingContext n’a pas besoin d’être transmise par la requête SQL.The StreamingContext value doesn't need to be passed in by the SQL query. Azure Stream Analytics fournit automatiquement un objet de contexte si un paramètre d’entrée est présent.Azure Stream Analytics provides a context object automatically if an input parameter is present. L’utilisation de MyUdfMethod ne change pas, comme illustré dans la requête suivante :The use of the MyUdfMethod does not change, as shown in the following query:

SELECT udf.MyUdfMethod(input.value) as udfValue FROM input

Vous pouvez accéder aux messages du journal par le biais des journaux de diagnostic.You can access log messages through the diagnostic logs.

LimitesLimitations

La préversion des fonctions définies par l’utilisateur a les limitations suivantes :The UDF preview currently has the following limitations:

  • Les fonctions définies par l’utilisateur .NET Standard peuvent uniquement être créées dans Visual Studio Code ou Visual Studio et publiées sur Azure..NET Standard UDFs can only be authored in Visual Studio Code or Visual Studio and published to Azure. Les versions en lecture seule des fonctions définies par l’utilisateur .NET Standard peuvent être consultées sous Fonctions dans le portail Azure.Read-only versions of .NET Standard UDFs can be viewed under Functions in the Azure portal. La création de fonctions .NET Standard n’est pas prise en charge dans le portail Azure.Authoring of .NET Standard functions is not supported in the Azure portal.

  • L’éditeur de requêtes du portail Azure affiche une erreur quand vous utilisez des fonctions définies par l’utilisateur .NET Standard dans le portail.The Azure portal query editor shows an error when using .NET Standard UDF in the portal.

  • Comme le code personnalisé partage le contexte du moteur Azure Stream Analytics, il ne peut pas référencer un élément qui a un espace de noms/nom_dll en conflit avec le code Azure Stream Analytics.Because the custom code shares context with Azure Stream Analytics engine, custom code can't reference anything that has a conflicting namespace/dll_name with Azure Stream Analytics code. Par exemple, vous ne pouvez pas référencer Newtonsoft Json.For example, you can't reference Newtonsoft Json.

  • Les fichiers de support inclus dans le projet sont copiés dans le fichier zip UserCustomCode utilisé lors de la publication du travail dans le cloud.Supporting files included in the project are copied to the User Custom Code zip file that is used when you publish the job to the cloud. Tous les fichiers des sous-dossiers sont copiés directement à la racine du dossier UserCustomCode dans le cloud lorsqu’ils sont décompressés.All files in subfolders are copied directly to the root of the User Custom Code folder in the cloud when unzipped. Le fichier zip est « aplati » lors de la décompression.The zip is "flattened" when decompressed.

  • UserCustomCode ne gère pas les dossiers vides.User Custom Code doesn't support empty folders. N’ajoutez pas de dossiers vides aux fichiers de support dans le projet.Don't add empty folders to the supporting files in the project.

Étapes suivantesNext steps