Desenvolver funções do .NET Standard definidas pelo usuário para trabalhos do Azure Stream Analytics (versão prévia)

  • Artigo

Importante

As funções definidas pelo usuário do .Net Standard para o Azure Stream Analytics serão desativadas em 30 de setembro de 2024. Após essa data, não será possível usar o recurso. Faça a transição para funções definidas pelo usuário do JavaScript para o Azure Stream Analytics.

O Azure Stream Analytics oferece uma linguagem de consulta semelhante à SQL para executar transformações e cálculos sobre fluxos de dados de eventos. Há muitas funções internas, mas alguns cenários complexos exigem flexibilidade adicional. Com as UDF (funções definidas pelo usuário) do .NET Standard, é possível invocar suas próprias funções gravadas em qualquer linguagem padrão do .NET (C#, F# etc.) para estender a linguagem de consulta do Stream Analytics. As UDFs permitem que você execute cálculos matemáticos complexos, importe modelos de ML personalizados usando ML.NET e use lógica de imputação personalizada para dados ausentes. O recurso UDF para trabalhos do Stream Analytics está atualmente em versão prévia e não deve ser usado nas cargas de trabalho de produção.

Regiões

O recurso de função definida pelo usuário do .NET é habilitado para trabalhos de nuvem executados em clusters do Stream Analytics. Os trabalhos executados no SKU Standard de multilocatário podem aproveitar esse recurso nas seguintes regiões públicas:

  • Centro-Oeste dos EUA
  • Norte da Europa
  • Leste dos EUA
  • Oeste dos EUA
  • Leste dos EUA 2
  • Europa Ocidental

Se você estiver interessado em usar essa funcionalidade em qualquer outra região, é possível solicitar acesso.

Caminho do pacote

O formato de qualquer pacote UDF possui o caminho /UserCustomCode/CLR/*. As DLLs (Bibliotecas de Vínculo Dinâmico) e os recursos são copiados na pasta /UserCustomCode/CLR/*, o que ajuda a isolar DLLs do usuário do sistema e DLLs do Azure Stream Analytics. Esse caminho de pacote é usado para todas as funções, independentemente do método usado para empregá-las.

Tipos com suporte e mapeamento

Para que os valores do Azure Stream Analytics sejam usados em C#, é necessário realizar marshaling deles de um ambiente para o outro. Marshaling ocorre para todos os parâmetros de entrada de um UDF. Cada tipo de Azure Stream Analytics tem um tipo correspondente em C# mostrado na tabela abaixo:

Tipo do Azure Stream Analytics Tipo de C#
BIGINT long
FLOAT double
nvarchar(max) string
DATETIME Datetime
Record Dicionário<cadeia de caracteres, objeto>
Array Objeto[]

O mesmo é verdadeiro quando é necessário realizar marshaling dos dados de C# para o Azure Stream Analytics, o que acontece no valor de saída de um UDF. A tabela a seguir mostra quais tipos têm suporte:

Tipo de C# Tipo do Azure Stream Analytics
long BIGINT
double FLOAT
string nvarchar(max)
Datetime dateTime
struct Record
objeto Record
Objeto[] Array
Dicionário<cadeia de caracteres, objeto> Record

Desenvolver um UDF no Visual Studio Code

As ferramentas do Visual Studio Code para Azure Stream Analytics facilitam a gravação de UDFs, testam os trabalhos localmente (mesmo offline) e publicam o trabalho do Stream Analytics no Azure.

Há duas maneiras de implementar UDFs do .NET Standard em ferramentas do Visual Studio Code.

  • UDF de DLLs locais
  • UDF de um projeto local

Projeto local

As funções definidas pelo usuário podem ser gravadas em um assembly que é posteriormente referenciado em uma consulta do Azure Stream Analytics. Essa é a opção recomendada para funções complexas que exigem todo o potencial de uma linguagem .NET Standard além de sua linguagem de expressão como lógica de procedimento ou recursão. As UDFs de um projeto local também podem ser usadas quando for necessário compartilhar a lógica de função em várias consultas do Azure Stream Analytics. Adicionar UDFs ao projeto local permite depurar e testar as funções localmente.

Para referenciar um projeto local:

  1. Crie uma nova biblioteca de classes do .NET Standard no computador local.
  2. Grave o código da classe. Lembre-se de que as classes devem ser definidas como públicas e os objetos devem ser definidos como públicos estáticos.
  3. Adicione um novo arquivo de configuração da Função CSharp ao seu projeto do Azure Stream Analytics e referencie o projeto da biblioteca de classes CSharp.
  4. Configure o caminho do assembly no arquivo de configuração do trabalho, JobConfig.json, seção CustomCodeStorage. Esta etapa não é necessária para testes locais.

DLLs locais

Também é possível referenciar DLLs locais que incluem as funções definidas pelo usuário.

Exemplo

Neste exemplo, CSharpUDFProject é um projeto de biblioteca de classes de C# e ASAUDFDemo é o projeto do Azure Stream Analytics que fará referência a CSharpUDFProject.

Azure Stream Analytics project in Visual Studio Code

O UDF a seguir tem uma função que multiplica um inteiro por si só para produzir o quadrado do inteiro. Todas as classes devem ser definidas como públicas e todos os objetos devem ser definidos como públicos estáticos.

using System;

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

As etapas a seguir mostram como adicionar a função UDF de C# ao seu projeto do Stream Analytics.

  1. Clique com o botão direito do mouse na pasta Funções e escolha Adicionar Item.

    Add new function in Azure Stream Analytics project

  2. Adicione uma função C# SquareFunction ao projeto do Azure Stream Analytics.

    Select CSharp function from Stream Analytics project in VS Code

    Enter CSharp function name in VS Code

  3. Na configuração da função C#, selecione Escolher o caminho do projeto de biblioteca para escolher seu projeto C# na lista suspensa e selecione Compilar projeto para compilar seu projeto. Em seguida, escolha Selecionar classe e Selecionar método para selecionar a classe relacionada e o nome do método na lista suspensa. Para fazer referência aos métodos, tipos e funções na consulta do Stream Analytics, as classes devem ser definidas como públicas e os objetos devem ser definidos como públicos estáticos.

    Stream Analytics C sharp function configuration VS Code

    Se desejar usar o UDF de C# de uma DLL, selecione Escolher caminho da DLL de biblioteca para escolher a DLL. Em seguida, escolha Selecionar classe e Selecionar método para selecionar a classe relacionada e o nome do método na lista suspensa.

    Stream Analytics C sharp function configuration

  4. Invoque o UDF em sua consulta do Azure Stream Analytics.

     SELECT price, udf.SquareFunction(price)
 INTO Output
 FROM Input

  5. Antes de enviar o trabalho para o Azure, configure o caminho do pacote no arquivo de configuração do trabalho, JobConfig.json, seção CustomCodeStorage. Use Selecione a partir da sua assinatura no CodeLens para escolher sua assinatura e escolha a conta de armazenamento e o nome do contêiner na lista suspensa. Deixe Caminho como padrão. Esta etapa não é necessária para testes locais.

    Choose library path

Desenvolver um UDF no Visual Studio

Há três maneiras de implementar UDFs nas ferramentas do Visual Studio.

  • Arquivos CodeBehind em um projeto ASA
  • UDF de um projeto local
  • Um pacote existente de uma conta de armazenamento do Azure

CodeBehind

É possível gravar funções definidas pelo usuário no CodeBehind do Script.asql. As ferramentas do Visual Studio compilarão automaticamente o arquivo CodeBehind em um arquivo do assembly. Os assemblies são empacotados como um arquivo zip e carregados na conta de armazenamento quando você envia o trabalho para o Azure. Você pode aprender como gravar uma UDF em C# usando CodeBehind seguindo o tutorial UDF em C# para trabalhos do Edge do Stream Analytics.

Projeto local

Para referenciar um projeto local no Visual Studio:

  1. Criar uma nova biblioteca de classes do .NET Standard em sua solução
  2. Grave o código da classe. Lembre-se de que as classes devem ser definidas como públicas e os objetos devem ser definidos como públicos estáticos.
  3. Compile o projeto. As ferramentas empacotarão todos os artefatos na pasta bin em um arquivo zip e carregarão o arquivo zip na conta de armazenamento. Para obter referências externas, use a referência de assembly em vez do pacote NuGet.
  4. Faça referência à nova classe no projeto do Azure Stream Analytics.
  5. Adicione uma nova função no projeto do Azure Stream Analytics.
  6. Configure o caminho do assembly no arquivo de configuração do trabalho, JobConfig.json. Defina o caminho do assembly para Referência de projeto local ou CodeBehind.
  7. Recompile o projeto de função e o projeto do Azure Stream Analytics.

Exemplo

Neste exemplo, UDFTest é um projeto de biblioteca de classes C# e ASAUDFDemo é o projeto do Azure Stream Analytics, que referenciará UDFTest.

Azure Stream Analytics IoT Edge project in Visual Studio

  1. Crie o projeto C#, que permitirá adicionar uma referência à UDF em C# a partir da consulta do Azure Stream Analytics.

    Build an Azure Stream Analytics IoT Edge project in Visual Studio

  2. Adicione a referência ao projeto C# no projeto do ASA. Clique com o botão direito do mouse no nó References e escolha Adicionar Referência.

    Add a reference to a C# project in Visual Studio

  3. Escolha o nome do projeto C# na lista.

    Choose your C# project name from the reference list

  4. Você deve ver o UDFTest listado em Referências no Gerenciador de Soluções.

    View the user defined function reference in solution explorer

  5. Clique com o botão direito do mouse na pasta Funções e escolha Novo Item.

    Add new item to Functions in Azure Stream Analytics Edge solution

  6. Adicione uma função C# SquareFunction.json ao projeto do Azure Stream Analytics.

    Select CSharp function from Stream Analytics Edge items in Visual Studio

  7. Clique duas vezes na função no Gerenciador de Soluções para abrir a caixa de diálogo de configuração.

    C sharp function configuration in Visual Studio

  8. Na configuração de função C#, escolha Carregar da Referência do Projeto ASA e os nomes de métodos, classe e assembly relacionados na lista suspensa. Para fazer referência aos métodos, tipos e funções na consulta do Stream Analytics, as classes devem ser definidas como públicas e os objetos devem ser definidos como públicos estáticos.

    Stream Analytics C sharp function configuration Visual Studio

Pacotes existentes

É possível criar UDFs do .NET Standard em qualquer IDE de sua escolha e invocá-las na consulta do Azure Stream Analytics. Primeiro compile o código e empacote todas as DLLs. O formato do pacote tem o caminho /UserCustomCode/CLR/*. Em seguida, carregue UserCustomCode.zip para a raiz do contêiner na conta de armazenamento do Azure.

Depois que os pacotes zip de assembly forem carregados na conta de armazenamento do Azure, será possível usar as funções nas consultas do Azure Stream Analytics. Basta incluir as informações de armazenamento na configuração do trabalho do Stream Analytics. Não é possível testar a função localmente com essa opção porque as ferramentas do Visual Studio não farão download do pacote. O caminho do pacote é analisado diretamente para o serviço.

Para configurar o caminho do assembly no arquivo de configuração de trabalho, JobConfig.json:

Expanda o a configuração de código definidos pelo usuário seção e, em seguida, preencha a configuração com os seguintes valores sugeridos:

Configuração Valor Sugerido
Recurso de Configurações de Armazenamento Global Escolha fonte de dados da conta atual
Assinatura de Configurações de Armazenamento Global < sua assinatura >
Conta de armazenamento das Configurações de Armazenamento Global < sua conta de armazenamento >
Recurso de Configurações de Armazenamento de Código Personalizado Escolha fonte de dados da conta atual
Conta de Armazenamento de Configurações de Armazenamento de Código Personalizado < sua conta de armazenamento >
Contêiner de Configurações de Armazenamento de Código Personalizado < seu contêiner de armazenamento >
Origem do assembly de código personalizado Pacotes existentes do assembly da nuvem
Origem do assembly de código personalizado UserCustomCode.zip

Registro em log do usuário

O mecanismo de registro em log permite que você capture informações personalizadas enquanto um trabalho está em execução. Você pode usar dados de log para depurar ou avaliar a exatidão do código personalizado em tempo real.

A classe StreamingContext permite a publicação de informações de diagnóstico usando a função StreamingDiagnostics.WriteError. O código a seguir mostra a interface exposta pelo 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 é passado como um parâmetro de entrada para o método UDF e pode ser usado no UDF para publicar informações de log personalizadas. No exemplo a seguir, MyUdfMethod define uma entrada de dados que é fornecida pela consulta e uma entrada de contexto como a StreamingContext fornecida pelo mecanismo de tempo de execução.

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

O valor StreamingContext não precisa ser passado pela consulta SQL. O Azure Stream Analytics fornece um objeto de contexto automaticamente se um parâmetro de entrada estiver presente. O uso do MyUdfMethod não é alterado, conforme mostrado na seguinte consulta:

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

Você pode acessar mensagens de log por meio de logs de diagnóstico.

Limitações

A versão prévia da UDF atualmente possui as seguintes limitações:

  • Os UDFs do .NET Standard somente podem ser criados no Visual Studio Code e publicadas no Azure. As versões somente leitura das UDFs do .NET Standard podem ser exibidas em Funções no portal do Azure. Não há suporte para a criação de funções do .NET Standard no portal do Azure.

  • O editor de consulta do portal do Azure mostra um erro ao usar a UDF do .NET Standard no portal.

  • Chamar pontos de extremidade REST externos, por exemplo, executar pesquisa inversa de IP ou extrair de dados de referência de uma fonte externa

  • Como o código personalizado compartilha o contexto com o mecanismo do Azure Stream Analytics, o código personalizado não pode fazer referência a nada que tenha um namespace/dll_name conflitante com o código do Azure Stream Analytics. Por exemplo, não é possível referenciar Newtonsoft Json.

  • Os arquivos de suporte incluídos no projeto são copiados para o arquivo zip de código personalizado do usuário que é usado quando o trabalho é publicado na nuvem. Todos os arquivos nas subpastas são copiados diretamente para a raiz da pasta de código personalizado do usuário na nuvem quando descompactados. O zip é "mesclado" quando descompactado.

  • O código personalizado do usuário não dá suporte a pastas vazias. Não adicione pastas vazias aos arquivos de suporte no projeto.

Próximas etapas