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

  • 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 utilizar o recurso. Faça a transição para funções JavaScript definidas pelo usuário para o Azure Stream Analytics.

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

Regiões

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

  • E.U.A. Centro-Oeste
  • Europa do Norte
  • E.U.A. Leste
  • E.U.A. Oeste
  • E.U.A. Leste 2
  • Europa Ocidental

Se você estiver interessado em usar esse recurso em qualquer outra região, você pode solicitar acesso.

Caminho do pacote

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

Tipos e mapeamento suportados

Para que os valores do Azure Stream Analytics sejam usados em C#, eles precisam ser empacotados de um ambiente para o outro. O marshaling acontece para todos os parâmetros de entrada de um UDF. Cada tipo do Azure Stream Analytics tem um tipo correspondente em C# mostrado na tabela abaixo:

Tipo do Azure Stream Analytics Tipo C#
bigint long
flutuante duplo
nvarchar (máx.) string
datetime DateTime
Registo Cadeia de dicionário<, objeto>
Matriz Objeto[]

O mesmo acontece quando os dados precisam ser empacotados do C# para o Azure Stream Analytics, o que acontece no valor de saída de um UDF. A tabela abaixo mostra quais tipos são suportados:

Tipo C# Tipo do Azure Stream Analytics
long bigint
duplo flutuante
string nvarchar (máx.)
DateTime dateTime
estruturar Registo
objeto Registo
Objeto[] Matriz
Cadeia de dicionário<, objeto> Registo

Desenvolver um UDF no Visual Studio Code

As ferramentas de código do Visual Studio para Azure Stream Analytics facilitam a escrita de UDFs, o teste de seus trabalhos localmente (mesmo offline) e a publicação de seu trabalho do Stream Analytics no Azure.

Há duas maneiras de implementar UDFs padrão do .NET nas ferramentas de código do Visual Studio.

  • 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 é referenciado posteriormente em uma consulta do Azure Stream Analytics. Esta é a opção recomendada para funções complexas que exigem o poder total de uma linguagem .NET Standard além de sua linguagem de expressão, como lógica processual ou recursão. UDFs de um projeto local também podem ser usados quando você precisa compartilhar a lógica de função em várias consultas do Azure Stream Analytics. Adicionar UDFs ao seu projeto local lhe dá a capacidade de depurar e testar suas funções localmente.

Para fazer referência a um projeto local:

  1. Crie uma nova biblioteca de classes padrão do .NET em sua máquina local.
  2. Escreva o código na sua 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 em seu projeto do Azure Stream Analytics e faça referência ao projeto de biblioteca de classes CSharp.
  4. Configure o caminho do assembly no arquivo de configuração do trabalho, JobConfig.jsonseção CustomCodeStorage . Esta etapa não é necessária para testes locais.

DLLs locais

Você também pode fazer referência a DLLs locais que incluem as funções definidas pelo usuário.

Exemplo

Neste exemplo, CSharpUDFProject é um projeto de biblioteca de classe 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. As classes devem ser definidas como públicas e 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 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 seu 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 caminho do projeto de biblioteca para escolher seu projeto C# na lista suspensa e selecione Construir projeto para construir seu projeto. Em seguida, escolha Select class e Select method para selecionar a classe relacionada e o nome do método na lista suspensa. Para se referir 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 você quiser usar o C# UDF de uma DLL, selecione Choose library dll path para escolher a DLL. Em seguida, escolha Select class e Select method 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.jsonseção CustomCodeStorage . Use Select from your subscription no CodeLens para escolher sua Assinatura e escolha a conta de armazenamento e o nome do contêiner na lista suspensa. Deixe Path 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

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

Projeto local

Para fazer referência a um projeto local no Visual Studio:

  1. Crie uma nova biblioteca de classes padrão do .NET em sua solução
  2. Escreva o código na sua 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. Recompile o seu projeto. As ferramentas empacotarão todos os artefatos na pasta bin em um arquivo zip e carregarão o arquivo zip para a conta de armazenamento. Para referências externas, use referência de assembly em vez do pacote NuGet.
  4. Faça referência à nova classe em seu projeto do Azure Stream Analytics.
  5. Adicione uma nova função ao seu 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 como Referência do projeto local ou CodeBehind.
  7. Recrie o projeto de função e o projeto do Azure Stream Analytics.

Exemplo

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

Azure Stream Analytics IoT Edge project in Visual Studio

  1. Crie seu projeto C#, que permitirá que você adicione uma referência ao seu C# UDF 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 ASA. Clique com o botão direito do mouse no nó Referências 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 um SquareFunction.json de função C# ao seu 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 da função C#, escolha Load from ASA Project Reference e os nomes de assembly, classe e método relacionados na lista suspensa. Para se referir 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

Você pode criar UDFs padrão do .NET em qualquer IDE de sua escolha e invocá-los a partir de sua consulta do Azure Stream Analytics. Primeiro, compile seu 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 em sua conta de armazenamento do Azure.

Depois que os pacotes zip de montagem forem carregados em sua conta de armazenamento do Azure, você poderá usar as funções nas consultas do Azure Stream Analytics. Tudo o que você precisa fazer é incluir as informações de armazenamento na configuração do trabalho do Stream Analytics. Você não pode testar a função localmente com essa opção porque as ferramentas do Visual Studio não baixarão seu pacote. O caminho do pacote é analisado diretamente para o serviço.

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

Expanda a secção Configuração do Código Definido Pelo Utilizador e preencha a configuração com os seguintes valores sugeridos:

Definição Valor Sugerido
Recurso de configurações globais de armazenamento Escolha a origem de dados na conta atual
Subscrição de Definições Globais de Armazenamento < a sua subscrição >
Conta de armazenamento de configurações globais de armazenamento < A sua conta de armazenamento >
Recurso de configurações de armazenamento de código personalizado Escolha a origem de dados na conta atual
Conta de armazenamento de configurações de armazenamento de código personalizado < A sua conta de armazenamento >
Contêiner de configurações de armazenamento de código personalizado < o seu recipiente de armazenamento >
Fonte de montagem de código personalizado Pacotes de montagem existentes a partir da nuvem
Fonte de montagem de código personalizado UserCustomCode.zip

Registo de utilizadores

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

A StreamingContext classe permite publicar informações de diagnóstico usando a StreamingDiagnostics.WriteError função. O código abaixo 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 dentro do UDF para publicar informações de log personalizadas. No exemplo abaixo, MyUdfMethod define uma entrada de dados , que é fornecida pela consulta, e uma entrada de contexto como , StreamingContextfornecida 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 StreamingContext valor 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 muda, conforme mostrado na consulta a seguir:

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

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

Limitações

A visualização UDF atualmente tem as seguintes limitações:

  • As UDFs padrão do .NET só podem ser criadas no Visual Studio Code ou Visual Studio e publicadas no Azure. As versões somente leitura de UDFs padrão do .NET podem ser exibidas em Funções no portal do Azure. A criação de funções .NET Standard não é suportada no portal do Azure.

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

  • Chamar pontos de extremidade REST externos, por exemplo, fazendo pesquisa reversa de IP ou extraindo dados de referência de uma fonte externa

  • Como o código personalizado compartilha 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, você não pode fazer referência a Newtonsoft Json.

  • Os arquivos de suporte incluídos no projeto são copiados para o arquivo zip do Código Personalizado do Usuário que é usado quando você publica o trabalho na nuvem. Todos os arquivos em subpastas são copiados diretamente para a raiz da pasta Código Personalizado do Usuário na nuvem quando descompactados. O fecho é "achatado" quando descomprimido.

  • O Código Personalizado do Usuário não suporta pastas vazias. Não adicione pastas vazias aos arquivos de suporte no projeto.

Próximos passos